Spring Security in Action

CONTENTSix

5 Implementing authentication		102				104
5.1	Understanding the AuthenticationProvider
	Representing the request during authentication				105
	Implementing custom authentication logic		106 ■			Applying
	custom authentication logic	108
5.2	Using the SecurityContext 113
	Using a holding strategy for the security context				114 ■		Using a
	holding strategy for asynchronous calls 116			■	Using a holding
	strategy for standalone applications 118		■	Forwarding the
	security context with DelegatingSecurityContextRunnable						119
	Forwarding the security context with DelegatingSecurityContext-
	ExecutorService 121

5.3Understanding HTTP Basic and form-based login authentications 124

	Using and configuring HTTP Basic		124 ■ Implementing
	authentication with form-based login		127
6 Hands-on: A small secured web application				135
6.1	Project requirements and setup		136
6.2	Implementing user management		141
6.3	Implementing custom authentication logic				146
6.4	Implementing the main page	148
6.5	Running and testing the application 151
7 Configuring authorization: Restricting access				153
7.1	Restricting access based on authorities and roles 155
	Restricting access for all endpoints based on user authorities 157
	Restricting access for all endpoints based on user roles 165
	Restricting access to all endpoints	169
8 Configuring authorization: Applying restrictions					172
8.1	Using matcher methods to select endpoints				173

8.2Selecting requests for authorization using MVC matchers 178

8.3Selecting requests for authorization using Ant matchers 185

8.4Selecting requests for authorization using regex matchers 190

CONTENTS	xiii
20.4 Testing method security	505

20.5Testing authentication 507

20.6	Testing CSRF configurations	510
20.7	Testing CORS configurations	511
20.8	Testing reactive Spring Security implementations 512
appendix A	Creating a Spring Boot project 515
	index 519

xvi

FOREWORD

Using Spring Security won’t address every security concern in your application, but fol- lowing the advice in this book will improve the security of your application immensely.

In summary, this book is timely, practical, and well written. I certainly plan to have a copy on my bookshelf. I suggest that all Java developers who care about the security of their applications do the same.

EOIN WOODS

CHIEF TECHNICAL OFFICER, ENDAVA

xviii

PREFACE

and that might even expose security vulnerabilities. Too many times, I’ve been con- sulted by teams working on applications in which I’ve discovered Spring Security being improperly used. And, in many cases, the main reason was the lack of under- standing of how to use Spring Security.

Because of this, I decided to write a book that helps any developer with Spring understand how to use Spring Security correctly. This book should be a resource to help someone with no knowledge of Spring Security understand it gradually. And what I hope, in the end, is that this book brings significant value to the reader with the time they’ll save in learning Spring Security and all the possible security vulnerabilities they’ll avoid introducing into their apps.

ABOUT THIS BOOK

xxi

well. For this reason, I chose to use Java for writing the examples for the book. If you feel more comfortable, any of these examples could be easily rewritten in Kotlin as well.

How this book is organized: A roadmap

This book is divided into two parts that cover 20 chapters. Part 1 of this book contains the first two chapters, in which we discuss security in general, and I teach you how to create a simple project that uses Spring Security:

In chapter 1, we discuss the importance of security in software applications and how you should think about security and vulnerabilities, which you’ll learn to avoid introducing into your apps by using Spring Security. This chapter prepares you for the rest of the book, where we use Spring Security in applied examples.

In chapter 2, you learn to create a simple Spring Boot project using Spring Security. We also discuss the Spring Security authentication and authorization architecture and its components on a high level. We start with straightforward examples and then, steadily throughout this book, you learn to apply detailed customizations for these components.

Part 2 of this book consists of eighteen chapters that progressively drive you through- out all the implementation details you need to understand to use Spring Security in your applications:

In chapter 3, you learn to use the Spring Security components that are related to user management. You learn how to describe a user with the interfaces pro- vided by Spring Security and how to implement the functionality that enables your application to load and manage user details.

In chapter 4, you learn how to manage user’s passwords with Spring Security. We discuss encryption, hashing, and the Spring Security components related to password validation. As you might expect, passwords are sensitive details and play an essential role in most security implementations. Knowing to manage passwords is a valuable skill that we dissect in detail in this chapter.

In chapter 5, you learn how to customize the authentication logic of your appli- cation using Spring Security components. After learning in chapter 2 that Spring Boot provides you with a default implementation for authentication logic, in this chapter, you discover further that for specific requirements in real- world scenarios, you need to define custom authentication logic.

In chapter 6, the first hands-on exercise, we create a small, secured web applica- tion. We put together everything you learned in chapters 2 through 5, and you find out how to assemble these pieces into a fully working app. This app is a more complex one, and it teaches you is how to assemble in a working app the custom- ized components you learned to develop while reading the previous chapters.

xxii	ABOUT THIS BOOK

In chapter 7, we start the discussion about authorization configuration, and you learn how to configure authorization constraints. As part of almost any applica- tion, we need to make sure that actions can be executed only by authorized calls. After learning in chapters 2 through 6 how to manage authentication, it’s time you configure whether the authenticated user has the privilege of executing cer- tain actions. You learn in this chapter how to deny or permit access for requests.

In chapter 8, we continue our discussion on authorization, and you learn how to apply authorization constraints for specific HTTP requests. In the previous chapter, we only refer to how to permit or deny requests depending on the cir- cumstances. In this chapter, you learn to apply different authorization configu- rations for specific requests depending on the path or the HTTP method.

In chapter 9, we discuss customizing the filter chain. You learn that the filter chain represents a chain of responsibility that intercepts the HTTP request to apply authentication and authorization configurations.

In chapter 10, we discuss how cross-site request forgery protection works, and you learn how to customize it with Spring Security. Then, we discuss cross-origin resource sharing, and you learn how to configure more relaxed CORS policies and when you should do this.

In chapter 11, our second hands-on exercise, we work on an application that implements customized authentication and authorization. You apply what you learned already in this book, but you also learn what tokens are and their pur- pose in authorization.

In chapter 12, we begin our journey into a more complex topic, OAuth 2. This topic is the subject of chapters 12 through 15. In this chapter, you learn what OAuth 2 is, and we discuss the flows in which a client can obtain an access token to call endpoints exposed by a backend application.

In chapter 13, you learn how to use Spring Security to build a custom OAuth 2 authorization server.

In chapter 14, you learn how to use Spring Security to build a resource server in your OAuth 2 system, as well as ways in which the resource server validates the tokens issued by the authorization server.

In chapter 15, we conclude the OAuth 2 topic with how systems use JSON Web Tokens for authorization.

In chapter 16, we discuss applying authorization configurations at the method level.

In chapter 17, we continue the discussion from chapter 16, and you learn how to apply authorization configurations to filter values that represent inputs and outputs of methods.

In chapter 18, our third hands-on exercise, we apply with an example what you learned in chapters 12 through 17. Moreover, you learn how to use the third- party tool Keycloak as an authorization server in your OAuth 2 system.

xxiv	ABOUT THIS BOOK

people who wanted to use JWTs without knowing how the basic Spring Security arc- hitecture works. This approach generally doesn’t work and leads to frustration. If you aren’t familiar yet with the basics and want to learn about OAuth2 applications, start with the beginning of the book, and don’t go directly to chapter 15.

OAuth 2

chapters 12 through 15

Method security

chapters 16 through 18

Testing

chapter 20

If you’re already comfortable with the basics and you’re interested only in a specific subject (for example, OAuth 2), you can skip to the first chapter that describes the topic of your interest.

You can also decide to read chapters 16 and 17 directly after chapter 11 if you’re not interested in OAuth 2. In that case, you can skip the OAuth 2 part completely. The OAuth 2 chapters are intended to be read in order, starting with chapter 12 and up through chapter 15. And it also makes sense to read the last hands-on chapter of the book, which is chapter 18, after you read both the OAuth 2 parts and chapters 16 and 17.

You may decide whether to read chapter 19 or not, which is related to securing reactive apps. This chapter is only relevant to reactive apps, so you can skip it if it’s not pertinent to your interests.

In the last chapter, chapter 20, you learn how to define your integration tests for security configurations. We use examples that were explained throughout the book, and you need to understand the concepts we discussed in all the previous chapters. However, I separated chapter 20 into multiple sections. Each section is directly related to the main concepts discussed in the book. So, if you need to learn how to write inte- gration tests, but you don’t care about reactive apps, you can still easily read chapter 20 and skip over the section referring to reactive apps.

ABOUT THIS BOOK

xxv

About the code

The book provides over 70 projects, which we work on starting with chapter 2 and up through chapter 19. When working on a specific example, I mention the name of the project that implements the example. My recommendation is that you try to write your own example from scratch together with the explanations in the book, and then only use the provided project to compare your solution with my solution. This approach helps you better understand the security configurations you’re learning.

Each of the projects is built with Maven, which makes it easy to be imported into any IDE. I used IntelliJ IDEA to write the projects, but you can run them in Eclipse, STS, NetBeans, or any other tool of your choice. The appendix also helps you as a refresher on how to create a Spring Boot project.

This book contains many examples of source code both in numbered listings and in line with normal text. In both cases, source code is formatted in a fixed-width font, like this to separate it from ordinary text. At times, the original source code has been reformatted; I added line breaks and reworked indentation to accommodate the available page space in the book. In rare cases, even this was not enough, and list- ings include line-continuation markers (➥). Code annotations accompany many of the listings, highlighting important concepts.

The liveBook discussion forum

Purchasing Spring Security in Action includes free access to a private web forum run by Manning Publications where you can make comments about the book, ask technical questions, and receive help from the author and from other users. To access the forum, go to http://mng.bz/6Awp. You can also learn more about Manning’s forums and the rules of conduct at https://livebook.manning.com/#!/discussion.

Manning’s commitment to our readers is to provide a venue where a meaningful dialogue between individual readers and between readers and the author can take place. It is not a commitment to any specific amount of participation on the part of the author, whose contribution to the forum remains voluntary (and unpaid). We sug- gest you try asking him some challenging questions lest his interest stray! The forum and the archives of previous discussions are accessible from the publisher’s website as long as the book is in print.

Other online resources

Additional resources include the Spring Security Reference at http://mng.bz/7Gz7 and the Spring Security Fundamentals playlist on the author’s YouTube account at http://mng.bz/mN4W.

Part 1

First Steps

Security is one of the essential nonfunctional qualities of a software system. One of the most crucial aspects you learn in this book is that you should con- sider security from the beginning stages of application development. In chapter 1, we start by discussing the place of security in the development process of an application. Then, in chapter 2, I introduce you to the basic components of Spring Security’s backbone architecture by implementing a few straightforward projects.

The purpose of this part is to get you started with Spring Security, especially if you are just beginning to learn this framework. However, even if you already know some aspects of application-level security and the underlying architecture of Spring Security, I recommend you read this part as a refresher.

4	CHAPTER 1 Security today

application works correctly from the user’s perspective and, in the end, it does what the user expects in terms of functionality, there are lots of aspects hidden in the final result.

Nonfunctional software qualities such as performance, scalability, availability, and, of course, security, as well as others, can have an impact over time, from short to long term. If not taken into consideration early on, these qualities can dramatically affect the profitability of the application owners. Moreover, the neglect of these consider- ations can also trigger failures in other systems as well (for example, by the unwilling participation in a distributed denial of service (DDoS) attack). The hidden aspects of nonfunctional requirements (the fact that it’s much more challenging to see if some- thing’s missing or incomplete) makes these, however, more dangerous.

Figure 1.1 A user mainly thinks about functional requirements. Sometimes, you might see them aware of performance, which is nonfunctional, but unfortunately, it’s quite unusual that a user cares about security. Nonfunctional requirements tend to be more transparent than functional ones.

There are multiple nonfunctional aspects to consider when working on a software sys- tem. In practice, all of these are important and need to be treated responsibly in the process of software development. In this book, we focus on one of these: security. You’ll learn how to protect your application, step by step, using Spring Security.

But before starting, I’d like to make you aware of the following: depending on how much experience you have, you might find this chapter cumbersome. Don’t worry too much if you don’t understand absolutely all the aspects for now. In this chapter, I want to show you the big picture of security-related concepts. Throughout the book, we

Spring Security: The what and the why

5

work on practical examples, and where appropriate, I’ll refer back to the description I give in this chapter. Where applicable, I’ll also provide you with more details. Here and there, you’ll find references to other materials (books, articles, documentation) on specific subjects that are useful for further reading.

1.1Spring Security: The what and the why

In this section, we discuss the relationship between Spring Security and Spring. It is important, first of all, to understand the link between the two before starting to use those. If we go to the official website, https://spring.io/projects/spring-security, we see Spring Security described as a powerful and highly customizable framework for authentication and access control. I would simply say it is a framework that enor- mously simplifies applying (or “baking”) security for Spring applications.

Spring Security is the primary choice for implementing application-level security in Spring applications. Generally, its purpose is to offer you a highly customizable way of implementing authentication, authorization, and protection against common attacks. Spring Security is an open source software released under the Apache 2.0 license. You can access its source code on GitHub at https://github.com/spring-projects/ spring-security/. I highly recommend that you contribute to the project as well.

NOTE You can use Spring Security for both standard web servlets and reac- tive applications. To use it, you need at least Java 8, although the examples in this book use Java 11, which is the latest long-term supported version.

I can guess that if you opened this book, you work on Spring applications, and you are interested in securing those. Spring Security is most likely the best choice for you. It’s the de facto solution for implementing application-level security for Spring applica- tions. Spring Security, however, doesn’t automatically secure your application. It’s not some kind of magic panacea that guarantees a vulnerability-free app. Developers need to understand how to configure and customize Spring Security around the needs of their applications. How to do this depends on many factors, from the functional requirements to the architecture.

Technically, applying security with Spring Security in Spring applications is simple. You’ve already implemented Spring applications, so you know that the framework’s philosophy starts with the management of the Spring context. You define beans in the Spring context to allow the framework to manage these based on the configurations you specify. And you use only annotations to make these configurations and leave behind the old-fashioned XML configuration style!

You use annotations to tell Spring what to do: expose endpoints, wrap methods in transactions, intercept methods in aspects, and so on. The same is true with Spring Security configurations, which is where Spring Security comes into play. What you want is to use annotations, beans, and in general, a Spring-fashioned configuration style comfortably when defining your application-level security. In a Spring applica- tion, the behavior that you need to protect is defined by methods.

6	CHAPTER 1 Security today

To think about application-level security, you can consider your home and the way you allow access to it. Do you place the key under the entrance rug? Do you even have a key for your front door? The same concept applies to applications, and Spring Secu- rity helps you develop this functionality. It’s a puzzle that offers plenty of choices for building the exact image that describes your system. You can choose to leave your house completely unsecured, or you can decide not to allow everyone to enter your home.

The way you configure security can be straightforward like hiding your key under the rug, or it can be more complicated like choosing a variety of alarm systems, video cameras, and locks. In your applications, you have the same options, but as in real life, the more complexity you add, the more expensive it gets. In an application, this cost refers to the way security affects maintainability and performance.

But how do you use Spring Security with Spring applications? Generally, at the application level, one of the most encountered use cases is when you’re deciding whether someone is allowed to perform an action or use some piece of data. Based on configurations, you write Spring Security components that intercept the requests and that ensure whoever makes the requests has permission to access protected resources. The developer configures components to do precisely what’s desired. If you mount an alarm system, it’s you who should make sure it’s also set up for the windows as well as for the doors. If you forget to set it up for the windows, it’s not the fault of the alarm system that it doesn’t trigger when someone forces a window.

Other responsibilities of Spring Security components relate to data storage as well as data transit between different parts of the systems. By intercepting calls to these dif- ferent parts, the components can act on the data. For example, when data is stored, these components can apply encryption or hashing algorithms. The data encodings keep the data accessible only to privileged entities. In a Spring application, the devel- oper has to add and configure a component to do this part of the job wherever it’s needed. Spring Security provides us with a contract through which we know what the framework requires to be implemented, and we write the implementation according to the design of the application. We can say the same thing about transiting data.

In real-world implementations, you’ll find cases in which two communicating com- ponents don’t trust each other. How can the first know that the second one sent a spe- cific message and it wasn’t someone else? Imagine you have a phone call with somebody to whom you have to give private information. How do you make sure that on the other end is indeed a valid individual with the right to get that data, and not somebody else? For your application, this situation applies as well. Spring Security provides components that allow you to solve these issues in several ways, but you have to know which part to configure and then set it up in your system. This way, Spring Security intercepts messages and makes sure to validate communication before the application uses any kind of data sent or received.

Like any framework, one of the primary purposes of Spring is to allow you to write less code to implement the desired functionality. And this is also what Spring Security does. It completes Spring as a framework by helping you write less code to perform one of the most critical aspects of an application—security. Spring Security provides

What is software security?

7

predefined functionality to help you avoid writing boilerplate code or repeatedly writ- ing the same logic from app to app. But it also allows you to configure any of its com- ponents, thus providing great flexibility. To briefly recap this discussion:

You use Spring Security to bake application-level security into your applications in the “Spring” way. By this, I mean, you use annotations, beans, the Spring Expression Language (SpEL), and so on.

Spring Security is a framework that lets you build application-level security. However, it is up to you, the developer, to understand and use Spring Security properly. Spring Security, by itself, does not secure an application or sensitive data at rest or in flight.

This book provides you with the information you need to effectively use Spring Security.

Alternatives to Spring Security

This book is about Spring Security, but as with any solution, I always prefer to have a broad overview. Never forget to learn the alternatives that you have for any option. One of the things I’ve learned over time is that there’s no general right or wrong. “Everything is relative” also applies here!

You won’t find a lot of alternatives to Spring Security when it comes to securing a Spring application. One alternative you could consider is Apache Shiro (https:// shiro.apache.org). It offers flexibility in configuration and is easy to integrate with Spring and Spring Boot applications. Apache Shiro sometimes makes a good alterna- tive to the Spring Security approach.

If you’ve already worked with Spring Security, you’ll find using Apache Shiro easy and comfortable to learn. It offers its own annotations and design for web applications based on HTTP filters, which greatly simplify working with web applications. Also, you can secure more than just web applications with Shiro, from smaller command-line and mobile applications to large-scale enterprise applications. And even if simple, it’s powerful enough to use for a wide range of things from authentication and authoriza- tion to cryptography and session management.

However, Apache Shiro could be too “light” for the needs of your application. Spring Security is not just a hammer, but an entire set of tools. It offers a larger scale of possibilities and is designed specifically for Spring applications. Moreover, it benefits from a larger community of active developers, and it is continuously enhanced.

1.2What is software security?

Software systems today manage large amounts of data, of which a significant part can be considered sensitive, especially given the current General Data Protection Regula- tions (GDPR) requirements. Any information that you, as a user, consider private is sensitive for your software application. Sensitive data can include harmless informa- tion like a phone number, email address, or identification number; although, we gen- erally think more about data that is riskier to lose, like your credit card details. The

What is software security?

11

Monolithic and microservices

The discussion on monolithic and microservices architectural styles is a whole differ- ent tome. I refer to these in multiple places in this book, so you should at least be aware of the terminology. For an excellent discussion of the two architectural styles, I recommend that you read Chris Richardson’s Microservices Patterns (Manning, 2018).

By monolithic architecture, we refer to an application in which we implement all the responsibilities in the same executable artifact. Consider this as one application that fulfills all use cases. The responsibilities can sometimes be implemented within dif- ferent modules to make the application more comfortable to maintain. But you can’t separate the logic of one from the logic of others at runtime. Generally, monolithic architectures offer less flexibility for scaling and deployment management.

With a microservices system, we implement the responsibilities within different exe- cutable artifacts. You can see the system as being formed of multiple applications that execute at the same time and communicate between themselves when needed via the network. While this offers more flexibility for scaling, it introduces other diffi- culties. We can enumerate here latencies, security concerns, network reliability, dis- tributed persistence, and deployment management.

I referred earlier to authentication and authorization. And, indeed, these are often present in most applications. Through authentication, an application identifies a user (a person or another application). The purpose of identifying these is to be able to decide afterward what they should be allowed to do—that’s authorization. I provide quite a lot of details on authentication and authorization, starting with chapter 3 and continuing throughout the book.

In an application, you often find the need to implement authorization in different scenarios. Consider another situation: most applications have restrictions regarding the user for obtaining access certain functionality. Achieving this implies first the need to identify who creates an access to request for a specific feature—that’s authentica- tion. As well, we need to know their privileges to allow the user to use that part of the system. As the system becomes more complex, you’ll find different situations that require a specific implementation related to authentication and authorization.

For example, what if you’d like to authorize a particular component of the system against a subset of data or operations on behalf of the user? Let’s say the printer needs access to read the user’s documents. Should you simply share the credentials of the user with the printer? But that allows the printer more rights than needed! And it also exposes the credentials of the user. Is there a proper way to do this without imperson- ating the user? These are essential questions, and the kind of questions you encounter when developing applications: questions that we not only want to answer, but for which you’ll see applications with Spring Security in this book.

12	CHAPTER 1 Security today

Depending on the chosen architecture for the system, you’ll find authentication and authorization at the level of the entire system, as well as for any of the components. And as you’ll see further along in this book, with Spring Security, you’ll sometimes pre- fer to use authorization even for different tiers of the same component. In chapter 16, we’ll discuss more on global method security, which refers to this aspect. The design gets even more complicated when you have a predefined set of roles and authorities.

I would also like to bring to your attention data storage. Data at rest adds to the responsibility of the application. Your app shouldn’t store all its data in a readable for- mat. The application sometimes needs to keep the data either encrypted with a pri- vate key or hashed. Secrets like credentials and private keys can also be considered data at rest. These should be carefully stored, usually in a secrets vault.

NOTE We classify data as “at rest” or “in transition.” In this context, data at rest refers to data in computer storage or, in other words, persisted data. Data in transition applies to all the data that’s exchanged from one point to another. Different security measures should, therefore, be enforced, depending on the type of data.

Finally, an executing application must manage its internal memory as well. It may sound strange, but data stored in the heap of the application can also present vulnera- bilities. Sometimes the class design allows the app to store sensitive data like creden- tials or private keys for a long time. In such cases, someone who has the privilege to make a heap dump could find these details and then use them maliciously.

With a short description of these cases, I hope I’ve managed to provide you with an overview of what we mean by application security, as well as the complexity of this sub- ject. Software security is a tangled subject. One who is willing to become an expert in this field would need to understand (as well as to apply) and then test solutions for all the layers that collaborate within a system. In this book, however, we’ll focus only on presenting all the details of what you specifically need to understand in terms of Spring Security. You’ll find out where this framework applies and where it doesn’t, how it helps, and why you should use it. Of course, we’ll do this with practical exam- ples that you should be able to adapt to your own unique use cases.

1.3Why is security important?

The best way to start thinking about why security is important is from your point of view as a user. Like anyone else, you use applications, and these have access to your data. These can change your data, use it, or expose it. Think about all the apps you use, from your email to your online banking service accounts. How would you evalu- ate the sensitivity of the data that is managed by all these systems? How about the actions that you can perform using these systems? Similarly to data, some actions are more important than others. You don’t care very much about some of those, while others are more significant. Maybe for you, it’s not that important if someone would somehow manage to read some of your emails. But I bet you’d care if someone else could empty your bank accounts.

Why is security important?

13

Once you’ve thought about security from your point of view, try to see a more objective picture. The same data or actions might have another degree of sensitivity to other people. Some might care a lot more than you if their email is accessed and someone could read their messages. Your application should make sure to protect everything to the desired degree of access. Any leak that allows the use of data and functionalities, as well as the application, to affect other systems is considered a vul- nerability, and you need to solve it.

Not respecting security comes with a price that I’m sure you aren’t willing to pay. In general, it’s about money. But the cost can differ, and there are multiple ways through which you can lose profitability. It isn’t only about losing money from a bank account or using a service without paying for it. These things indeed imply cost. The image of a brand or a company is also valuable, and losing a good image can be expensive—sometimes even more costly than the expenses directly resulting from the exploitation of a vulnerability in the system! The trust that users have in your applica- tion is one of its most valuable assets, and it can make the difference between success or failure.

Here are a few fictitious examples. Think about how you would see these as a user. How can these affect the organization responsible for the software?

A back-office application should manage the internal data of an organization but, somehow, some information leaks out.

Users of a ride-sharing application observe that money is debited from their accounts on behalf of trips that aren’t theirs.

After an update, users of a mobile banking application are presented with trans- actions that belong to other users.

In the first situation, the organization using the software, as well as its employees, can be affected. In some instances, the company could be liable and could lose a significant amount of money. In this situation, users don’t have the choice to change the applica- tion, but the organization can decide to change the provider of their software.

In the second case, users will probably choose to change the service provider. The image of the company developing the application would be dramatically affected. The cost lost in terms of money in this case is much less than the cost in terms of image. Even if payments are returned to the affected users, the application will still lose some customers. This affects profitability and can even lead to bankruptcy. And in the third case, the bank could see dramatic consequences in terms of trust, as well as legal repercussions.

In most of these scenarios, investing in security is safer than what happens if some- one exploits a vulnerability in your system. For all of the examples, only a small weak- ness could cause each outcome. For the first example, it could be a broken authentication or a cross-site request forgery (CSRF). For the second and third exam- ples, it could be a lack of method access control. And for all of these examples, it could be a combination of vulnerabilities.

14	CHAPTER 1 Security today

Of course, from here we can go even further and discuss the security in defense- related systems. If you consider money important, add human lives to the cost! Can you even imagine what could be the result if a health care system was affected? What about systems that control nuclear power? You can reduce any risk by investing early in the security of your application and by allocating enough time for security profes- sionals to develop and test your security mechanisms.

NOTE The lessons learned from those who failed before you are that the cost of an attack is usually higher than the investment cost of avoiding the vulnerability.

In the rest of this book, you’ll see examples of ways to apply Spring Security to avoid situations like the ones presented. I guess there will never be enough word written about how important security is. When you have to make a compromise on the secu- rity of your system, try to estimate your risks correctly.

1.4Common security vulnerabilities in web applications

Before we discuss how to apply security in your applications, you should first know what you’re protecting the application from. To do something malicious, an attacker identifies and exploits the vulnerabilities of your application. We often describe vul- nerability as a weakness that could allow the execution of actions that are unwanted, usually done with malicious intentions.

An excellent start to understanding vulnerabilities is being aware of the Open Web Application Security Project, also known as OWASP (https://www.owasp.org). At OWASP, you’ll find descriptions of the most common vulnerabilities that you should avoid in your applications. Let’s take a few minutes and discuss these theoretically before diving into the next chapters, where you’ll start to apply concepts from Spring Security. Among the common vulnerabilities that you should be aware of, you’ll find these:

Broken authentication

Session fixation

Cross-site scripting (XSS)

Cross-site request forgery (CSRF)

Injections

Sensitive data exposure

Lack of method access control

Using dependencies with known vulnerabilities

These items are related to application-level security, and most of these are also directly related to using Spring Security. We’ll discuss their relationship with Spring Security and how to protect your application from these in detail in this book, but first, an overview.

16	CHAPTER 1 Security today

the products belong when returning these? Some user could find a way to get the details of another user. This situation is just one of the examples that should be taken into con- sideration from the beginning of application design so that you can avoid this.

Throughout the book, we’ll refer to vulnerabilities. We’ll discuss vulnerabilities starting with the basic configuration of authentication and authorization in chapter 3. Then, we’ll discuss how vulnerabilities relate to the integration of Spring Security and Spring Data and how to design an application to avoid those, with OAuth 2.

1.4.2What is session fixation?

Session fixation vulnerability is a more specific, high-severity weakness of a web applica- tion. If present, it permits an attacker to impersonate a valid user by reusing a previ- ously generated session ID. This vulnerability can happen if, during the authentication process, the web application does not assign a unique session ID. This can potentially lead to the reuse of existing session IDs. Exploiting this vulnerability consists of obtain- ing a valid session ID and making the intended victim’s browser use it.

Depending on how you implement your web application, there are various ways an individual can use this vulnerability. For example, if the application provides the ses- sion ID in the URL, then the victim could be tricked into clicking on a malicious link. If the application uses a hidden attribute, the attacker can fool the victim into using a foreign form and then post the action to the server. If the application stores the value of the session in a cookie, then the attacker can inject a script and force the victim’s browser to execute it.

1.4.3What is cross-site scripting (XSS)?

Cross-site scripting, also referred to as XSS, allows the injection of client-side scripts into web services exposed by the server, thereby permitting other users to run these. Before being used or even stored, you should properly “sanitize” the request to avoid undesired executions of foreign scripts. The potential impact can relate to account impersonation (combined with session fixation) or to participation in distributed attacks like DDoS.

Let’s take an example. A user posts a message or a comment in a web application. After posting the message, the site displays it so that everybody visiting the page can see it. Hundreds might visit this page daily, depending on how popular the site is. For the sake of our example, we’ll consider it a known site, and a significant number of individuals visit its pages. What if this user posts a script that, when found on a web page, the browser executes (figures 1.6 and 1.7)?

18	CHAPTER 1 Security today

1.4.4What is cross-site request forgery (CSRF)?

Cross-site request forgery (CSRF) vulnerabilities are also common in web applications. CSRF attacks assume that a URL that calls an action on a specific server can be extracted and reused from outside the application (figure 1.8). If the server trusts the execution without doing any check on the origin of the request, one could execute it from any other place. Through CSRF, an attacker can make a user execute undesired actions on a server by hiding the actions. Usually, with this vulnerability, the attacker targets actions that change data in the system.

3.The forgery page contains a script that executes on behalf of the user. Upon accessing the forgery page, the script is sent to the user and the

browser executes it.

1. The user logs into their account.

4.The script executes actions on behalf of the user.

2. The user accesses a page that contains forgery code.

Figure 1.8 Steps of a cross-site request forgery (CSRF). After logging into their account, the user accesses a page that contains forgery code. The malicious code then executes actions on behalf of the unsuspecting user.

One of the ways of mitigating this vulnerability is to use tokens to identify the request or use cross-origin resource sharing (CORS) limitations. In other words, validate the origin of the request. We’ll look closer at how Spring Security deals with CSRF and CORS vulnerabilities in chapter 10.

1.4.5Understanding injection vulnerabilities in web applications

Injection attacks on systems are widespread. In an injection attack, the attacker employ- ing a vulnerability introduces specific data into the system. The purpose is to harm the system, to change data in an unwanted way, or to retrieve data that’s not meant to be accessed by the attacker.

There are many types of injection attacks. Even the XSS that we mentioned in sec- tion 1.4.3 can be considered an injection vulnerability. In the end, injection attacks inject a client-side script with the means of harming the system somehow. Other exam- ples could be SQL injection, XPath injection, OS command injection, LDAP injec- tion, and the list continues.

Common security vulnerabilities in web applications

19

Injection types of vulnerabilities are important, and the results of exploiting these can be change, deletion, or access to data in the systems being compromised. For example, if your application is somehow vulnerable to LDAP injection, an attacker could benefit from bypassing the authentication and from there control essential parts of the system. The same can happen for XPath or OS command injections.

One of the oldest and perhaps well-known types of injection vulnerability is SQL injection. If your application has an SQL injection vulnerability, an attacker can try to change or run different SQL queries to alter, delete, or extract data from your system. In the most advanced SQL injection attacks, an individual can run OS commands on the system, leading to a full system compromise.

1.4.6Dealing with the exposure of sensitive data

Even if, in terms of complexity, the disclosure of confidential data seems to be the eas- iest to understand and the least complex of the vulnerabilities, it remains one of the most common mistakes. Maybe this happens because the majority of tutorials and examples found online, as well as books illustrating different concepts, define the cre- dentials directly in the configuration files for simplicity reasons. In the case of a hypo- thetical example that eventually focuses on something else, this makes sense.

NOTE Most of the time, developers learn continuously from theoretical examples. Generally, examples are simplified to allow the reader to focus on a specific topic. But a downside of this simplification is that developers get used to wrong approaches. Developers might mistakenly think that everything they read is a good practice.

How is this aspect related to Spring Security? Well, we’ll deal with credentials and pri- vate keys in the examples in this book. We might use secrets in configuration files, but we’ll place a note for these cases to remind you that you should store sensitive data in vaults. Naturally, for a developed system, the developers aren’t allowed to see the val- ues for these sensitive keys in all of the environments. Usually, at least for production, only a small group of people should be allowed to access private data.

By setting such values in the configuration files, such as the application.properties or application .yml files in a Spring Boot project, you make those private values acces- sible to anyone who can see the source code. Moreover, you might also find yourself storing all the history of these value changes in your version management system for source code.

Also related to the exposure of sensitive data is the information in logs written by your application to the console or stored in databases such as Splunk or Elasticsearch. I often see logs that disclose sensitive data forgotten by the developers.

NOTE Never log something that isn’t public information. By public, I mean that anyone can see or access the info. Things like private keys or certificates aren’t public and shouldn’t be logged together with your error, warning, or info messages.

20	CHAPTER 1 Security today

Next time you log something from your application, make sure what you log doesn’t look like one of these messages:

[error] The signature of the request is not correct. The correct key to be used should have been X.

[warning] Login failed for username X and password Y. User with username X has password Z.

[info] A login was performed with success by user X with password Y.

Be careful of what your server returns to the client, especially, but not limited to, cases where the application encounters exceptions. Often due to lack of time or experi- ence, developers forget to implement all such cases. This way (and usually happening after a wrong request), the application returns too many details that expose the imple- mentations.

This application behavior is also a vulnerability through data exposure. If your app encounters a NullPointerException because the request is wrong (part of it is missing, for example), then the exception shouldn’t appear in the body of the response. At the same time, the HTTP status should be 400 rather than 500. HTTP status codes of type 4XX are designed to represent problems on the client side. A wrong request is, in the end, a client issue, so the application should represent it accordingly. HTTP status codes of type 5XX are designed to inform you that there is a problem on the server. Do you see something wrong in the response presented by the next snippet?

{

"status": 500,

"error": "Internal Server Error",

"message": "Connection not found for IP Address 10.2.5.8/8080",

"path": "/product/add"

}

The message of the exception seems to be disclosing an IP address. An attacker can use this address to understand the network configuration and, eventually, find a way to con- trol the VMs in your infrastructure. Of course, with only this piece of data, one can’t do any harm. But collecting different disclosed pieces of information and putting these together could provide everything that’s needed to adversely affect a system. Having exception stacks in the response is not a good choice either, for example:

at java.base/java.util.concurrent.ThreadPoolExecutor ➥.runWorker(ThreadPoolExecutor.java:1128) ~[na:na]

at java.base/java.util.concurrent.ThreadPoolExecutor$Worker ➥.run(ThreadPoolExecutor.java:628) ~[na:na]

at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable

➥.run(TaskThread.java:61) ~[tomcat-embed-core-9.0.26.jar:9.0.26] at java.base/java.lang.Thread.run(Thread.java:830) ~[na:na]

22	CHAPTER 1 Security today

1.4.7What is the lack of method access control?

Even at the application level, you don’t apply authorization to only one of the tiers. Sometimes, it’s a must to ensure that a particular use case can’t be called at all (for example, if the privileges of the currently authenticated user don’t allow it).

Say you have a web application with a straightforward design. The app has a con- troller exposing endpoints. The controller directly calls a service that implements some logic and that uses persisted data managed through a repository (figure 1.9). Imagine a situation where the authorization is done only at the endpoint level (assuming that you can access the method through a REST endpoint). A developer might be tempted to apply authorization rules only in the controller layer as presented in figure 1.9.

	Uses	Uses
AccountController	AccountService	AccountRepository

The developer applies the authorization configuration in the controller layer.

Figure 1.9 A developer applies the authorization rules at the controller layer. But the repository does not know the user and does not restrict the retrieval of data. If a service asks for accounts that don’t belong to the currently authenticated user, the repository returns these.

While the case presented in figure 1.9 works correctly, applying the authorization rules only at the controller layer can leave room for error. In this case, some future implementation could expose that use case without testing or without testing all the authorization requirements. In figure 1.10, you can see what can happen if a devel- oper adds another functionality that depends on the same repository.

These situations might appear, and you may need to treat these at any layer in your application, not just in the repository. We’ll discuss more things related to this subject in chapters 16 and 17. There, you’ll also learn how you can apply restrictions to each application tier when this is needed, as well as the cases when you should avoid doing this.

Common security vulnerabilities in web applications			23
1. The authorization configuration		3. So it’s better to move
regarding the account is applied here.
		the configuration here.
Uses		Uses
AccountController	AccountService
		AccountRepository
Uses
TransactionController	TransactionService
		Uses

2.But we also need to apply authorization configuration regarding accounts here now.

Figure 1.10 The newly added TransactionController makes use of the AccountRepository in its dependency chain. The developer must reapply the authorization rules in this controller as well. But it would be much better if the repository itself made sure that data that doesn’t belong to the authenticated user is not exposed.

1.4.8Using dependencies with known vulnerabilities

Although not necessarily directly related to Spring Security, but still an essential aspect of the application-level security, the dependencies we use need attention. Sometimes it’s not the application you develop that has vulnerabilities, but the depen- dencies like libraries or frameworks that you use to build the functionality. Always be attentive to the dependencies you use and eliminate any version that’s known to con- tain a vulnerability.

Fortunately, we have multiple possibilities for static analyses, quickly done by add- ing a plugin to your Maven or Gradle configuration. The majority of applications today are developed based on open source technologies. Even Spring Security is an open source framework. This development methodology is great, and it allows for fast evolution, but this can also make us more error prone.

When developing any piece of software, we have to take all the needed measures to avoid the use of any dependency that has known vulnerabilities. If we discover that we’ve used such a dependency, then we not only have to correct this fast, we also have to investigate if the vulnerability was already exploited in our applications and then take the needed measures.

24	CHAPTER 1 Security today

1.5Security applied in various architectures

In this section, we discuss applying security practices depending on the design of your system. It’s important to understand that different software architectures imply differ- ent possible leaks and vulnerabilities. In this first chapter, I want to make you aware of the philosophy to which I’ll refer to throughout the book.

Architecture strongly influences choices in configuring Spring Security for your applications; so do functional and nonfunctional requirements. When you think of a tangible situation, to protect something, depending on what you want to protect, you use a metal door, bulletproof glass, or a barrier. You couldn’t just use a metal door in all the situations. If what you protect is an expensive painting in a museum, you still want people to be able to see it. You don’t, however, want them to be able to touch it, damage it, or even take it with them. In this case, functional requirements affect the solution we take for secure systems.

It could be that you need to make a good compromise with other quality attributes like, for example, performance. It’s like using a heavy metal door instead of a light- weight barrier at the parking entrance. You could do that, and for sure, the metal door would be more secure, but it takes much more time to open and close it. The time and cost of opening and closing the heavy door aren’t worth it; of course, assum- ing that this isn’t some kind of special parking for expensive cars.

Because the security approach is different depending on the solution we imple- ment, the configuration in Spring Security is also different. In this section, we discuss some examples based on different architectural styles, that take into consideration var- ious requirements that affect the approach to security. These aspects are linked to all the configurations that we’ll work on with Spring Security in the following chapters.

In this section, I present some of the practical scenarios you might have to deal with and those we’ll work through in the rest of the book. For a more detailed discussion on techniques for securing apps in microservices systems, I recommend you also read Microservices Security in Action by Prabath Siriwardena and Nuwan Dias (Manning, 2019).

1.5.1Designing a one-piece web application

Let’s start with the case where you develop a component of a system that represents a web application. In this application, there’s no direct separation in development between the backend and the frontend. The way we usually see these kinds of applica- tions is through the general servlet flow: the application receives an HTTP request and sends back an HTTP response to a client. Sometimes, we might have a server-side session for each client to store specific details over more HTTP requests. In the exam- ples provided in the book, we use Spring MVC (figure 1.11).

You’ll find a great discussion about developing web applications and REST services with Spring in chapters 2 and 6 of Craig Walls’s Spring In Action, 6th ed. (Manning, 2020):

https://livebook.manning.com/book/spring-in-action-sixth-edition/chapter-2/ https://livebook.manning.com/book/spring-in-action-sixth-edition/chapter-6/

Security applied in various architectures		25
	Based on the URL path,
The request is received	the dispatcher finds the
by a dispatcher servlet.	associated controller action.

The client makes a
request to the server.	1	/login
		Handler Mappings
Request	2	login()	The action
			of the
	DispatcherServlet	Controller	controller
Response			is executed.
	3	login.html

View Resolver

The response is sent back to the client.

After the execution of the controller action, the view is found and rendered as the response.

Figure 1.11 A minimal representation of the Spring MVC flow. The DispatcherServlet finds the mapping of the requested path to the controller method (1), executes the controller method (2), and obtains the rendered view (3). The HTTP response is then delivered back to the requester, whereby the browser interprets and displays the response.

As long as you have a session, you need to take into consideration the session fixation vulnerability as well as the CSRF possibilities previously mentioned. You must also con- sider what you store in the HTTP session itself.

Server-side sessions are quasi-persistent. They are stateful pieces of data, so their lifetime is longer. The longer these stay in memory, the more it’s statistically probable that they’ll be accessed. For example, a person having access to the heap dump could read the information in the app’s internal memory. And don’t think that the heap dump is challenging to obtain! Especially when developing your applications with Spring Boot, you might find that the Actuator is also part of your application. The Spring Boot Actuator is a great tool. Depending on how you configure it, it can return a heap dump with only an endpoint call. That is, you don’t necessarily need root access to the VM to get your dump.

Going back to the vulnerabilities in terms of CSRF in this case, the easiest way to mitigate the vulnerability is to use anti-CSRF tokens. Fortunately, with Spring Security, this capability is available out of the box. CSRF protection as well as validation of the origin CORS is enabled by default. You’ll have to disable it if you don’t want it explic- itly. For authentication and authorization, you could choose to use the implicit login form configuration from Spring Security. With this, you’ll benefit from only needing to override the look and feel of the login and log-out, and from the default integra- tion with the authentication and authorization configuration. You also benefit from mitigation of the session fixation vulnerability.

Security applied in various architectures

27

In terms of security, there are some other aspects to be taken into consideration. First, CSRF and CORS configurations are usually more complicated. You might want to scale the system horizontally, but it’s not mandatory to have the frontend with the backend at the same origin. For mobile applications, we can’t even talk about an origin.

The most straightforward but least desirable approach as a practical solution is to use HTTP Basic for endpoint authentication. While this approach is direct to under- stand and generally used with the first theoretical examples of authentication, it does have leaks that you want to avoid. For example, using HTTP Basic implies sending the credentials with each call. As you’ll see in chapter 2, credentials aren’t encrypted. The browser sends the username and the passwords as a Base64 encoding. This way, the credentials are left available on the network in the header of each endpoint call. Also, assuming that the credentials represent the user that’s logged in, you don’t want the user to type their credentials for every request. You also don’t want to have to store the credentials on client side. This practice is not advisable.

Having the stated reasons in mind, chapter 12 gives you an alternative for authen- tication and authorization that offers a better approach, the OAuth 2 flow, and the fol- lowing section provides an overview of this approach.

A short reminder of application scalability

Scalability refers to the quality of a software application in which it can serve more or fewer requests while adapting the resources used, without the need to change the application or its architecture. Mainly, we classify scalability into two types: vertical and horizontal.

When a system is scaled vertically, the resources of the system on which it executes are adapted to the need of the application (for example, when there are more requests, more memory and processing power are added to the system).

We accomplish horizontal scalability by changing the number of instances of the same application that are in execution (for example, if there are more requests, another instance is started to serve the increased need). Of course, I assume the newly spun-up application instances consume resources offered by additional hard- ware, sometimes even in multiple data centers. If the demand decreases, we can reduce the instance numbers.

1.5.3Understanding the OAuth 2 flow

In this section, we discuss a high-level overview of the OAuth 2 flow. I focus on the rea- son for applying OAuth 2 and how it relates to what we discussed in section 1.5.2. We’ll discuss this topic in detail in chapters 12 through 15. We certainly want to find a solution to avoid resending credentials for each of the requests to the backend and store these on the client side. The OAuth 2 flow offers a better way to implement authentication and authorization in these cases.

Security applied in various architectures

29

access card can open some of the doors, but not necessarily all. Based on your identity, you can access precisely the doors that you’re allowed to and no more. The same hap- pens with an access token. After authentication, the caller is provided with a token, and based on that, they can access the resources for which they have privileges.

A token has a fixed lifetime, usually being short-lived. When a token expires, the app needs to obtain a new one. If needed, the server can disqualify the token earlier than its expiration time. The following lists some of the advantages of this flow:

The client doesn’t have to store the user credentials. The access token and, eventually, the refresh token are the only access details you need to save.

The application doesn’t expose the user credentials, which are often on the network.

If someone intercepts a token, you can disqualify the token without needing to invalidate the user credentials.

A token can be used by a third entity to access resources on the user’s behalf, without having to impersonate the user. Of course, an attacker can steal the token in this case. But because the token usually has a limited lifespan, the time- frame in which one can use this vulnerability is limited.

NOTE To make it simple and only give you an overview, I’ve described the OAuth 2 flow called the password grant type. OAuth 2 defines multiple grant types and, as you’ll see in chapters 12 through 15, the client application does not always have the credentials. If we use the authorization code grant, the application redirects the authentication in the browser directly to a login implemented by the authorization server. But more on this later in the book.

Of course, not everything is perfect even with the OAuth 2 flow, and you need to adapt it to the application design. One of the questions could be, which is the best way to manage the tokens? In the examples that we’ll work on in chapters 12 through 15, we’ll cover multiple possibilities:

Persisting the tokens in the app’s memory

Persisting the tokens in a database

Using cryptographic signatures with JSON Web Tokens (JWT)

1.5.4Using API keys, cryptographic signatures, and IP validation to secure requests

In some cases, you don’t need a username and a password to authenticate and autho- rize a caller, but you still want to make sure that nobody altered the exchanged mes- sages. You might need this approach when requests are made between two backend components. Sometimes you’d like to make sure that messages between these are

30	CHAPTER 1 Security today

validated somehow (for example, if you deploy your backend as a group of services or you use another backend external to your system). For this, a few practices include

Using static keys in request and response headers

Signing requests and responses with cryptographic signatures

Applying validation for IP addresses

The use of static keys is the weakest approach. In the headers of the request and the response, we use a key. Requests and responses aren’t accepted if the header value is incorrect. Of course, this assumes that we often exchange the value of the key in the network; if the traffic goes outside the data center, it would be easy to intercept. Some- one who gets the value of the key could replay the call on the endpoint. When we use this approach, it’s usually done together with IP address whitelisting.

A better approach to test the authenticity of communication is the use of crypto- graphic signatures (figure 1.14). With this approach, a key is used to sign the request and the response. You don’t need to send the key on the wire, which is an advantage over static authorization values. The parties can use their key to validate the signature. The implementation can be done using two asymmetric key pairs. This approach assumes that we never exchange the private key. A simpler version uses a symmetric key, which requires a first-time exchange for configuration. The disadvantage is that the computation of a signature consumes more resources.

Would you give me that info?

HTTP 403 Forbidden

I don't know your signature. Sorry!

Would you give me that info?

HTTP 200 OK.

I know your signature. Here it is!

Figure 1.14 To make a successful call to another backend, the request should have the correct signature or shared key.

Summary

31

If you know an address or range of addresses from where a request should come, then together with one of the solutions mentioned previously, IP address validation can be applied. This method implies that the application rejects requests if coming from IP addresses other than the ones that you configure to be accepted. However, in most cases, IP validation is not done at the application level but much earlier, in the net- working layer.

1.6What will you learn in this book?

This book offers a practical approach to learning Spring Security. Throughout the rest of the book, we’ll deep dive into Spring Security, step by step, proving concepts with simple to more complex examples. To get the most out of this book, you should be comfortable with Java programming, as well as with the basics of the Spring Frame- work. If you haven’t used the Spring Framework or you don’t feel comfortable yet using its basics, I recommend you first read Spring In Action, 6th ed., by Craig Walls (Manning, 2020). Another great resource is Spring Boot In Action by Craig Walls (Man- ning, 2015). But in this book, you’ll learn

The architecture and basic components of Spring Security and how to use it to secure your application

Authentication and authorization with Spring Security, including the OAuth 2 and OpenID Connect flows, and how these apply to a production-ready application

How to implement security with Spring Security in different layers of your appli- cation

Different configuration styles and best practices for using those in your project

Using Spring Security for reactive applications

Testing your security implementations

To make the learning process smooth for each described concept, we’ll work on mul- tiple simple examples. At the end of each significant subject, we’ll review the essential concepts you’ve learned with a more complex application in chapters whose titles begin with “Hands-On.”

When we finish, you’ll know how to apply Spring Security for the most practical scenarios and understand where to use it and its best practices. I also strongly recom- mend that you work on all the examples that accompany the explanations.

Summary

Spring Security is the leading choice for securing Spring applications. It offers a significant number of alternatives that apply to different styles and architec- tures.

You should apply security in layers for your system, and for each layer, you need to use different practices.

32	CHAPTER 1 Security today

Security is a cross-cutting concern you should consider from the beginning of a software project.

Usually, the cost of an attack is higher than the cost of investment in avoiding vulnerabilities to begin with.

The Open Web Application Security Project is an excellent place to refer to when it comes to vulnerabilities and security concerns.

Sometimes the smallest mistakes can cause significant harm. For example, exposing sensitive data through logs or error messages is a common way to introduce vulnerabilities in your application.

34	CHAPTER 2 Hello Spring Security

less visible in the past when we developed most architectures monolithically. With a monolithic architecture, you only had to write these configurations once at the begin- ning, and you rarely needed to touch them afterward. When service-oriented software architectures evolved, we started to feel the pain of boilerplate code that we needed to write for configuring each service. If you find it amusing, you can check out chapter 3 from Spring in Practice by Willie Wheeler with Joshua White (Manning, 2013). This chapter of an older book describes writing a web application with Spring 3. In this way, you’ll understand how many configurations you had to write for one small one-page web application. Here’s the link for the chapter:

https://livebook.manning.com/book/spring-in-practice/chapter-3/

For this reason, with the development of recent apps and especially those for microservices, Spring Boot became more and more popular. Spring Boot provides autoconfiguration for your project and shortens the time needed for the setup. I would say it comes with the appropriate philosophy for today’s software development.

In this chapter, we’ll start with our first application that uses Spring Security. For the apps that you develop with the Spring Framework, Spring Security is an excellent choice for implementing application-level security. We’ll use Spring Boot and discuss the defaults that are autoconfigured, as well as a brief introduction to overriding these defaults. Considering the default configurations provides an excellent introduction to Spring Security, one that also illustrates the concept of authentication.

Once we get started with the first project, we’ll discuss various options for authenti- cation in more detail. In chapters 3 through 6, we’ll continue with more specific con- figurations for each of the different responsibilities that you’ll see in this first example. You’ll also see different ways to apply those configurations, depending on architectural styles. The steps we’ll approach in the current chapter follow:

1Create a project with only Spring Security and web dependencies to see how it behaves if you don’t add any configuration. This way, you’ll understand what you should expect from the default configuration for authentication and autho- rization.

2Change the project to add functionality for user management by overriding the defaults to define custom users and passwords.

3After observing that the application authenticates all the endpoints by default, learn that this can be customized as well.

4Apply different styles for the same configurations to understand best practices.

2.1Starting with the first project

Let’s create the first project so that we have something to work on for the first exam- ple. This project is a small web application, exposing a REST endpoint. You’ll see how, without doing much, Spring Security secures this endpoint using HTTP Basic authen- tication. Just by creating the project and adding the correct dependencies, Spring

Starting with the first project

35

Boot applies default configurations, including a username and a password when you start the application.

NOTE You have various alternatives to create Spring Boot projects. Some development environments offer the possibility of creating the project directly. If you need help with creating your Spring Boot projects, you can find several ways described in the appendix. For even more details, I recom- mend Craig Walls’ Spring Boot in Action (Manning, 2016). Chapter 2 from Spring Boot in Action accurately describes creating a web app with Spring Boot (https://livebook.manning.com/book/spring-boot-in-action/chapter-2/).

The examples in this book refer to the source code. With each example, I also specify the dependencies that you need to add to your pom.xml file. You can, and I recom- mend that you do, download the projects provided with the book and the available source code at https://www.manning.com/downloads/2105. The projects will help you if you get stuck with something. You can also use these to validate your final solutions.

NOTE The examples in this book are not dependent on the build tool you choose. You can use either Maven or Gradle. But to be consistent, I built all the examples with Maven.

The first project is also the smallest one. As mentioned, it’s a simple application expos- ing a REST endpoint that you can call and then receive a response as described in fig- ure 2.1. This project is enough to learn the first steps when developing an application with Spring Security. It presents the basics of the Spring Security architecture for authentication and authorization.

curl -u user:pass http://localhost:8080/hello

200 OK Hello!

Figure 2.1 Our first application uses HTTP Basic to authenticate and authorize the user against an endpoint. The application exposes a REST endpoint at a defined path (/hello). For a successful call, the response returns an HTTP 200 status message and a body. This example demonstrates how the authentication and authorization configured by default with Spring Security works.

We begin learning Spring Security by creating an empty project and naming it ssia-ch2-ex1. (You’ll also find this example with the same name in the projects provided with the book.) The only dependencies you need to write for our first project are spring-boot-starter-web and spring-boot-starter-security, as shown in

36	CHAPTER 2 Hello Spring Security

listing 2.1. After creating the project, make sure that you add these dependencies to your pom.xml file. The primary purpose of working on this project is to see the behav- ior of a default configured application with Spring Security. We also want to understand which components are part of this default configuration, as well as their purpose.

Listing 2.1 Spring Security dependencies for our first web app

<dependency>

<groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId>

</dependency>

<dependency>

<groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId>

</dependency>

We could directly start the application now. Spring Boot applies the default configura- tion of the Spring context for us based on which dependencies we add to the project. But we wouldn’t be able to learn much about security if we don’t have at least one end- point that’s secured. Let’s create a simple endpoint and call it to see what happens. For this, we add a class to the empty project, and we name this class Hello- Controller. To do that, we add the class in a package called controllers some- where in the main namespace of the Spring Boot project.

NOTE Spring Boot scans for components only in the package (and its sub- packages) that contains the class annotated with @SpringBootApplication. If you annotate classes with any of the stereotype components in Spring outside of the main package, you must explicitly declare the location using the @ComponentScan annotation.

In the following listing, the HelloController class defines a REST controller and a REST endpoint for our example.

Listing 2.2 The HelloController class and a REST endpoint

@RestController

public class HelloController {

@GetMapping("/hello") public String hello() {

return "Hello!";

}

}

The @RestController annotation registers the bean in the context and tells Spring that the application uses this instance as a web controller. Also, the annotation speci- fies that the application has to set the returned value from the body of the HTTP response. The @GetMapping annotation maps the /hello path to the implemented

Starting with the first project

37

method. Once you run the application, besides the other lines in the console, you should see something that looks similar to this:

Using generated security password: 93a01cf0-794b-4b98-86ef-54860f36f7f3

Each time you run the application, it generates a new password and prints this pass- word in the console as presented in the previous code snippet. You must use this pass- word to call any of the application’s endpoints with HTTP Basic authentication. First, let’s try to call the endpoint without using the Authorization header:

curl http://localhost:8080/hello

NOTE In this book, we use cURL to call the endpoints in all the examples. I consider cURL to be the most readable solution. But if you prefer, you can use a tool of your choice. For example, you might want to have a more com- fortable graphical interface. In this case, Postman is an excellent choice. If the operating system you use does not have any of these tools installed, you prob- ably need to install them yourself.

And the response to the call:

{

"status":401,

"error":"Unauthorized",

"message":"Unauthorized",

"path":"/hello"

}

The response status is HTTP 401 Unauthorized. We expected this result as we didn’t use the proper credentials for authentication. By default, Spring Security expects the default username (user) with the provided password (in my case, the one starting with

93a01). Let’s try it again but now with the proper credentials:

curl -u user:93a01cf0-794b-4b98-86ef-54860f36f7f3 http://localhost:8080/hello

The response to the call now is

Hello!

NOTE The HTTP 401 Unauthorized status code is a bit ambiguous. Usually, it’s used to represent a failed authentication rather than authorization. Devel- opers use it in the design of the application for cases like missing or incorrect credentials. For a failed authorization, we’d probably use the 403 Forbidden status. Generally, an HTTP 403 means that the server identified the caller of the request, but they don’t have the needed privileges for the call that they are trying to make.

Once we send the correct credentials, you can see in the body of the response pre- cisely what the HelloController method we defined earlier returns.

38	CHAPTER 2 Hello Spring Security

Calling the endpoint with HTTP Basic authentication

With cURL, you can set the HTTP basic username and password with the -u flag. Behind the scenes, cURL encodes the string <username>:<password> in Base64 and sends it as the value of the Authorization header prefixed with the string Basic. And with cURL, it’s probably easier for you to use the -u flag. But it’s also essential to know what the real request looks like. So, let’s give it a try and manually create the Authorization header.

In the first step, take the <username>:<password> string and encode it with Base64. When our application makes the call, we need to know how to form the correct value for the Authorization header. You do this using the Base64 tool in a Linux console. You could also find a web page that encodes strings in Base64, like https://www.base64encode.org. This snippet shows the command in a Linux or a Git Bash console:

echo -n user:93a01cf0-794b-4b98-86ef-54860f36f7f3 | base64

Running this command returns this Base64-encoded string:

dXNlcjo5M2EwMWNmMC03OTRiLTRiOTgtODZlZi01NDg2MGYzNmY3ZjM=

You can now use the Base64-encoded value as the value of the Authorization header for the call. This call should generate the same result as the one using the -u option:

curl -H "Authorization: Basic dXNlcjo5M2EwMWNmMC03OTRiLTRiOTgtODZlZi01 ➥NDg2MGYzNmY3ZjM=" http://localhost:8080/hello

The result of the call is

Hello!

There’s no significant security configurations to discuss with a default project. We mainly use the default configurations to prove that the correct dependencies are in place. It does little for authentication and authorization. This implementation isn’t something we want to see in a production-ready application. But the default project is an excellent example that you can use for a start.

With this first example working, at least we know that Spring Security is in place. The next step is to change the configurations such that these apply to the require- ments of our project. First, we’ll go deeper with what Spring Boot configures in terms of Spring Security, and then we see how we can override the configurations.

2.2Which are the default configurations?

In this section, we discuss the main actors in the overall architecture that take part in the process of authentication and authorization. You need to know this aspect because you’ll have to override these preconfigured components to fit the needs of your appli- cation. I’ll start by describing how Spring Security architecture for authentication and authorization works and then we’ll apply that to the projects in this chapter. It would

40	CHAPTER 2 Hello Spring Security

In figure 2.2, you can see that

The authentication filter delegates the authentication request to the authenti- cation manager and, based on the response, configures the security context.

The authentication manager uses the authentication provider to process authentication.

The authentication provider implements the authentication logic.

The user details service implements user management responsibility, which the authentication provider uses in the authentication logic.

The password encoder implements password management, which the authenti- cation provider uses in the authentication logic.

The security context keeps the authentication data after the authentication process.

In the following paragraphs, I’ll discuss these autoconfigured beans:

UserDetailsService

PasswordEncoder

You can see these in figure 2.2 as well. The authentication provider uses these beans to find users and to check their passwords. Let’s start with the way you provide the needed credentials for authentication.

An object that implements a UserDetailsService contract with Spring Security manages the details about users. Until now, we used the default implementation pro- vided by Spring Boot. This implementation only registers the default credentials in the internal memory of the application. These default credentials are “user” with a default password that’s a universally unique identifier (UUID). This password is ran- domly generated when the Spring context is loaded. At this time, the application writes the password to the console where you can see it. Thus, you can use it in the example we just worked on in this chapter.

This default implementation serves only as a proof of concept and allows us to see that the dependency is in place. The implementation stores the credentials in memory—the application doesn’t persist the credentials. This approach is suitable for examples or proof of concepts, but you should avoid it in a production-ready application.

And then we have the PasswordEncoder. The PasswordEncoder does two things:

Encodes a password

Verifies if the password matches an existing encoding

Even if it’s not as obvious as the UserDetailsService object, the Password- Encoder is mandatory for the Basic authentication flow. The simplest implementa- tion manages the passwords in plain text and doesn’t encode these. We’ll discuss more details about the implementation of this object in chapter 4. For now, you should be

Which are the default configurations?

41

aware that a PasswordEncoder exists together with the default UserDetails- Service. When we replace the default implementation of the UserDetails- Service, we must also specify a PasswordEncoder.

Spring Boot also chooses an authentication method when configuring the defaults, HTTP Basic access authentication. It’s the most straightforward access authentication method. Basic authentication only requires the client to send a user- name and a password through the HTTP Authorization header. In the value of the header, the client attaches the prefix Basic, followed by the Base64 encoding of the string that contains the username and password, separated by a colon (:).

NOTE HTTP Basic authentication doesn’t offer confidentiality of the creden- tials. Base64 is only an encoding method for the convenience of the transfer; it’s not an encryption or hashing method. While in transit, if intercepted, any- one can see the credentials. Generally, we don’t use HTTP Basic authentica- tion without at least HTTPS for confidentiality. You can read the detailed definition of HTTP Basic in RFC 7617 (https://tools.ietf.org/html/rfc7617).

The AuthenticationProvider defines the authentication logic, delegating the user and password management. A default implementation of the Authentication- Provider uses the default implementations provided for the UserDetailsService and the PasswordEncoder. Implicitly, your application secures all the endpoints. Therefore, the only thing that we need to do for our example is to add the endpoint. Also, there’s only one user who can access any of the endpoints, so we can say that there’s not much to do about authorization in this case.

HTTP vs. HTTPS

You might have observed that in the examples I presented, I only use HTTP. In prac- tice, however, your applications communicate only over HTTPS. For the examples we discuss in this book, the configurations related to Spring Security aren’t different, whether we use HTTP or HTTPS. So that you can focus on the examples related to Spring Security, I won’t configure HTTPS for the endpoints in the examples. But, if you want, you can enable HTTPS for any of the endpoints as presented in this sidebar.

There are several patterns to configure HTTPS in a system. In some cases, develop- ers configure HTTPS at the application level; in others, they might use a service mesh or they could choose to set HTTPS at the infrastructure level. With Spring Boot, you can easily enable HTTPS at the application level, as you’ll learn in the next example in this sidebar.

In any of these configuration scenarios, you need a certificate signed by a certifica- tion authority (CA). Using this certificate, the client that calls the endpoint knows whether the response comes from the authentication server and that nobody inter- cepted the communication. You can buy such a certificate, but you have to renew it. If you only need to configure HTTPS to test your application, you can generate a

Overriding default configurations

43

If you use a self-signed certificate, you should configure the tool you use to make the endpoint call so that it skips testing the authenticity of the certificate. If the tool tests the authenticity of the certificate, it won’t recognize it as being authentic, and the call won’t work. With cURL, you can use the -k option to skip testing the authenticity of the certificate:

curl -k https://localhost:8080/hello!

The response to the call is

Hello!

Remember that even if you use HTTPS, the communication between components of your system isn’t bulletproof. Many times, I’ve heard people say, “I’m not encrypting this anymore, I use HTTPS!” While helpful in protecting communication, HTTPS is just one of the bricks of the security wall of a system. Always treat the security of your system with responsibility and take care of all the layers involved in it.

2.3Overriding default configurations

Now that you know the defaults of your first project, it’s time to see how you can replace these. You need to understand the options you have for overriding the default components because this is the way you plug in your custom implementations and apply security as it fits your application. And, as you’ll learn in this section, the devel- opment process is also about how you write configurations to keep your applications highly maintainable. With the projects we’ll work on, you’ll often find multiple ways to override a configuration. This flexibility can create confusion. I frequently see a mix of different styles of configuring different parts of Spring Security in the same applica- tion, which is undesirable. So this flexibility comes with a caution. You need to learn how to choose from these, so this section is also about knowing what your options are.

In some cases, developers choose to use beans in the Spring context for the config- uration. In other cases, they override various methods for the same purpose. The speed with which the Spring ecosystem evolved is probably one of the main factors that generated these multiple approaches. Configuring a project with a mix of styles is not desirable as it makes the code difficult to understand and affects the maintainabil- ity of the application. Knowing your options and how to use them is a valuable skill, and it helps you better understand how you should configure application-level secu- rity in a project.

In this section, you’ll learn how to configure a UserDetailsService and a PasswordEncoder. These two components take part in authentication, and most applications customize them depending on their requirements. While we’ll discuss details about customizing them in chapters 3 and 4, it’s essential to see how to plug in a custom implementation. The implementations we use in this chapter are all pro- vided by Spring Security.

44	CHAPTER 2 Hello Spring Security

2.3.1Overriding the UserDetailsService component

The first component we talked about in this chapter was UserDetailsService. As you saw, the application uses this component in the process of authentication. In this section, you’ll learn to define a custom bean of type UserDetailsService. We’ll do this to override the default one provided by Spring Security. As you’ll see in more detail in chapter 3, you have the option to create your own implementation or to use a predefined one provided by Spring Security. In this chapter, we aren’t going to detail the implementations provided by Spring Security or create our own implementation just yet. I’ll use an implementation provided by Spring Security, named InMemory- UserDetailsManager. With this example, you’ll learn how to plug this kind of object into your architecture.

NOTE Interfaces in Java define contracts between objects. In the class design of the application, we use interfaces to decouple objects that use one another. To enforce this interface characteristic when discussing those in this book, I mainly refer to them as contracts.

To show you the way to override this component with an implementation that we choose, we’ll change what we did in the first example. Doing so allows us to have our own managed credentials for authentication. For this example, we don’t implement our class, but we use an implementation provided by Spring Security.

In this example, we use the InMemoryUserDetailsManager implementation. Even if this implementation is a bit more than just a UserDetailsService, for now, we only refer to it from the perspective of a UserDetailsService. This implementa- tion stores credentials in memory, which can then be used by Spring Security to authenticate a request.

NOTE An InMemoryUserDetailsManager implementation isn’t meant for production-ready applications, but it’s an excellent tool for examples or proof of concepts. In some cases, all you need is users. You don’t need to spend the time implementing this part of the functionality. In our case, we use it to understand how to override the default UserDetailsService implementation.

We start by defining a configuration class. Generally, we declare configuration classes in a separate package named config. Listing 2.3 shows the definition for the configu- ration class. You can also find the example in the project ssia-ch2-ex2.

NOTE The examples in this book are designed for Java 11, which is the latest long-term supported Java version. For this reason, I expect more and more applications in production to use Java 11. So it makes a lot of sense to use this version for the examples in this book.

You’ll sometimes see that I use var in the code. Java 10 introduced the reserved type name var, and you can only use it for local declarations. In this book, I use it to make

Overriding default configurations

45

the syntax shorter, as well as to hide the variable type. We’ll discuss the types hidden by var in later chapters, so you don’t have to worry about that type until it’s time to ana- lyze it properly.

Listing 2.3 The configuration class for the UserDetailsService bean

	The @Configuration
	annotation marks the class
@Configuration	as a configuration class.
		The @Bean annotation instructs
public class ProjectConfig {
		Spring to add the returned value
@Bean		as a bean in the Spring context.
public UserDetailsService userDetailsService() {
var userDetailsService =
new InMemoryUserDetailsManager();		The var word makes the syntax

shorter and hides some details.

return userDetailsService;

}

}

We annotate the class with @Configuration. The @Bean annotation instructs Spring to add the instance returned by the method to the Spring context. If you execute the code exactly as it is now, you’ll no longer see the autogenerated password in the con- sole. The application now uses the instance of type UserDetailsService you added to the context instead of the default autoconfigured one. But, at the same time, you won’t be able to access the endpoint anymore for two reasons:

You don’t have any users.

You don’t have a PasswordEncoder.

In figure 2.2, you can see that authentication depends on a PasswordEncoder as well. Let’s solve these two issues step by step. We need to

1Create at least one user who has a set of credentials (username and password)

2Add the user to be managed by our implementation of UserDetailsService

3Define a bean of the type PasswordEncoder that our application can use to verify a given password with the one stored and managed by UserDetails- Service

First, we declare and add a set of credentials that we can use for authentication to the instance of InMemoryUserDetailsManager. In chapter 3, we’ll discuss more about users and how to manage them. For the moment, let’s use a predefined builder to cre- ate an object of the type UserDetails.

When building the instance, we have to provide the username, the password, and at least one authority. The authority is an action allowed for that user, and we can use any string for this. In listing 2.4, I name the authority read, but because we won’t use this authority for the moment, this name doesn’t really matter.

Overriding default configurations

47

To solve this problem, we can add a PasswordEncoder bean in the context, the same as we did with the UserDetailsService. For this bean, we use an existing imple-

mentation of PasswordEncoder:

@Bean

public PasswordEncoder passwordEncoder() { return NoOpPasswordEncoder.getInstance();

}

NOTE The NoOpPasswordEncoder instance treats passwords as plain text. It doesn’t encrypt or hash them. For matching, NoOpPasswordEncoder only compares the strings using the underlying equals(Object o) method of the String class. You shouldn’t use this type of PasswordEncoder in a pro- duction-ready app. NoOpPasswordEncoder is a good option for examples where you don’t want to focus on the hashing algorithm of the password. Therefore, the developers of the class marked it as @Deprecated, and your development environment will show its name with a strikethrough.

You can see the full code of the configuration class in the following listing.

Listing 2.5 The full definition of the configuration class

@Configuration

public class ProjectConfig {

@Bean

public UserDetailsService userDetailsService() {

var userDetailsService = new InMemoryUserDetailsManager();

var user = User.withUsername("john")

.password("12345")

.authorities("read")

.build();

userDetailsService.createUser(user);

return userDetailsService;

}

@Bean

	public PasswordEncoder passwordEncoder() {	A new method annotated
		with @Bean to add a
	return NoOpPasswordEncoder.getInstance();
		PasswordEncoder to the context
	}

}

Let’s try the endpoint with the new user having the username John and the password 12345:

curl -u john:12345 http://localhost:8080/hello Hello!

48	CHAPTER 2 Hello Spring Security

NOTE Knowing the importance of unit and integration tests, some of you might already wonder why we don’t also write tests for our examples. You will actually find the related Spring Security integration tests with all the examples provided with this book. However, to help you focus on the presented topics for each chapter, I have separated the discussion about testing Spring Secu- rity integrations and detail this in chapter 20.

2.3.2Overriding the endpoint authorization configuration

With new management for the users in place, as described in section 2.3.1, we can now discuss the authentication method and configuration for endpoints. You’ll learn plenty of things regarding authorization configuration in chapters 7, 8, and 9. But before diving into details, you must understand the big picture. And the best way to achieve this is with our first example. With default configuration, all the endpoints assume you have a valid user managed by the application. Also, by default, your app uses HTTP Basic authentication as the authorization method, but you can easily over- ride this configuration.

As you’ll learn in the next chapters, HTTP Basic authentication doesn’t fit into most application architectures. Sometimes we’d like to change it to match our appli- cation. Similarly, not all endpoints of an application need to be secured, and for those that do, we might need to choose different authorization rules. To make such changes, we start by extending the WebSecurityConfigurerAdapter class. Extend- ing this class allows us to override the configure(HttpSecurity http) method as presented in the next listing. For this example, I’ll continue writing the code in the project ssia-ch2-ex2.

Listing 2.6 Extending WebSecurityConfigurerAdapter

@Configuration

public class ProjectConfig

extends WebSecurityConfigurerAdapter {

// Omitted code

@Override

protected void configure(HttpSecurity http) throws Exception { // ...

}

}

We can then alter the configuration using different methods of the HttpSecurity object as shown in the next listing.

Overriding default configurations

51

In listing 2.9, you can observe that we declar the UserDetailsService in the same way as in listing 2.5. The difference is that now this is done locally inside the second overridden method. We also call the userDetailsService() method from the AuthenticationManagerBuilder to register the UserDetailsService instance. Furthermore, we call the passwordEncoder() method to register the Password- Encoder. Listing 2.10 shows the full contents of the configuration class.

NOTE The WebSecurityConfigurerAdapter class contains three differ- ent overloaded configure() methods. In listing 2.9, we overrode a different one than in listing 2.8. In the next chapters, we’ll discuss all three in more detail.

Listing 2.10 Full definition of the configuration class

@Configuration

public class ProjectConfig extends WebSecurityConfigurerAdapter {

@Override

protected void configure

➥(AuthenticationManagerBuilder auth) throws Exception {

	var userDetailsService =
	new InMemoryUserDetailsManager();		Creates an instance of
	var user = User.withUsername("john")		InMemoryUserDetailsManager()
	.password("12345")	Creates a new user
	.authorities("read")
	.build();		Adds the user to be managed
	userDetailsService.createUser(user);		by our UserDetailsService

auth.userDetailsService(userDetailsService)

	.passwordEncoder(	Configures UserDetailsService
		and PasswordEncoder
	NoOpPasswordEncoder.getInstance());
	}

@Override

protected void configure(HttpSecurity http) throws Exception {

http.httpBasic();	Specifies that all the requests
http.authorizeRequests()
.anyRequest().authenticated();	require authentication
}

}

Any of these configuration options are correct. The first option, where we add the beans to the context, lets you inject the values in another class where you might potentially need them. But if you don’t need that for your case, the second option would be equally good. However, I recommend you avoid mixing configurations because it might create confusion. For example, the code in the following listing could make you wonder about where the link between the UserDetailsService and PasswordEncoder is.

52	CHAPTER 2 Hello Spring Security

Listing 2.11 Mixing configuration styles

@Configuration

public class ProjectConfig

extends WebSecurityConfigurerAdapter {

	@Bean
	public PasswordEncoder passwordEncoder() {	Designs the PasswordEncoder
	return NoOpPasswordEncoder.getInstance();
		as a bean
	}

@Override

protected void configure

➥(AuthenticationManagerBuilder auth) throws Exception { var userDetailsService = new InMemoryUserDetailsManager();

var user = User.withUsername("john")

.password("12345")

.authorities("read")

.build();

userDetailsService.createUser(user);

	auth.userDetailsService(userDetailsService);	Configures the UserDetailsService
}
		directly in the configure() method

@Override

protected void configure(HttpSecurity http) throws Exception { http.httpBasic();

http.authorizeRequests()

.anyRequest().authenticated();

}

}

Functionally, the code in listing 2.11 works just fine, but again, I recommend you avoid mixing the two approaches to keep the code clean and easier to understand. Using the AuthenticationManagerBuilder, you can configure users for authenti- cation directly. It creates the UserDetailsService for you in this case. The syntax, however, becomes even more complex and could be considered difficult to read. I’ve seen this choice more than once, even with production-ready systems.

It could be that this example looks fine because we use an in-memory approach to configure users. But in a production application, this isn’t the case. There, you proba- bly store your users in a database or access them from another system. As in this case, the configuration could become pretty long and ugly. Listing 2.12 shows the way you can write the configuration for in-memory users. You’ll find this example applied in the project ssia-ch2-ex4.

Listing 2.12 Configuring in-memory user management

@Override

protected void configure

➥(AuthenticationManagerBuilder auth) throws Exception {

54	CHAPTER 2 Hello Spring Security

Figure 2.3 shows the AuthenticationProvider, which implements the authentica- tion logic and delegates to the UserDetailsService and PasswordEncoder for user and password management. So we could say that with this section, we go one step deeper in the authentication and authorization architecture to learn how to imple- ment custom authentication logic with AuthenticationProvider.

Because this is a first example, I only show you the brief picture so that you better understand the relationship between the components in the architecture. But we’ll detail more in chapters 3, 4, and 5. In those chapters, you’ll find the AuthenticationProvider implemented, as well as in a more significant exercise, the first “Hands-On” section of the book, chapter 6.

I recommend that you respect the responsibilities as designed in the Spring Secu- rity architecture. This architecture is loosely coupled with fine-grained responsibili- ties. That design is one of the things that makes Spring Security flexible and easy to integrate in your applications. But depending on how you make use of its flexibility, you could change the design as well. You have to be careful with these approaches as they can complicate your solution. For example, you could choose to override the default AuthenticationProvider in a way in which you no longer need a User- DetailsService or PasswordEncoder. With that in mind, the following listing shows how to create a custom authentication provider. You can find this example in the project ssia-ch2-ex5.

Listing 2.13 Implementing the AuthenticationProvider interface

@Component

public class CustomAuthenticationProvider ➥implements AuthenticationProvider {

@Override

public Authentication authenticate

➥(Authentication authentication) throws AuthenticationException {

// authentication logic here

}

@Override

public boolean supports(Class<?> authenticationType) {

// type of the Authentication implementation here

}

}

The authenticate(Authentication authentication) method represents all the logic for authentication, so we’ll add an implementation like that in listing 2.14. I’ll explain the usage of the supports() method in detail in chapter 5. For the moment, I recommend you take its implementation for granted. It’s not essential for the current example.

Overriding default configurations	55
Listing 2.14 Implementing the authentication logic
@Override
public Authentication authenticate
➥(Authentication authentication)	The getName() method is
throws AuthenticationException {	inherited by Authentication
	from the Principal interface.
String username = authentication.getName();
String password = String.valueOf(authentication.getCredentials());
if ("john".equals(username) &&
"12345".equals(password)) {	This condition generally calls
return new UsernamePasswordAuthenticationToken	UserDetailsService and
	PasswordEncoder to test the
➥(username, password, Arrays.asList());	username and password.

}else {

throw new AuthenticationCredentialsNotFoundException

➥("Error in authentication!");

}

}

As you can see, here the condition of the if-else clause is replacing the responsibil- ities of UserDetailsService and PasswordEncoder. Your are not required to use the two beans, but if you work with users and passwords for authentication, I strongly suggest you separate the logic of their management. Apply it as the Spring Security architecture designed it, even when you override the authentication implementation.

You might find it useful to replace the authentication logic by implementing your own AuthenticationProvider. If the default implementation doesn’t fit entirely into your application’s requirements, you can decide to implement custom authenti- cation logic. The full AuthenticationProvider implementation looks like the one in the next listing.

Listing 2.15 The full implementation of the authentication provider

@Component

public class CustomAuthenticationProvider ➥implements AuthenticationProvider {

@Override

public Authentication authenticate ➥(Authentication authentication)

throws AuthenticationException {

String username = authentication.getName();

String password = String.valueOf(authentication.getCredentials());

if ("john".equals(username) && "12345".equals(password)) {

return new UsernamePasswordAuthenticationToken ➥(username, password, Arrays.asList());

} else {

Overriding default configurations

57

complex. In a production-ready application, you probably have more declarations than in our first examples. You also might find it useful to have more than one config- uration class to make the project readable.

It’s always a good practice to have only one class per each responsibility. For this example, we can separate user management configuration from authorization config- uration. We do that by defining two configuration classes: UserManagementConfig (defined in listing 2.17) and WebAuthorizationConfig (defined in listing 2.18). You can find this example in the project ssia-ch2-ex6.

Listing 2.17 Defining the configuration class for user and password management

@Configuration

public class UserManagementConfig {

@Bean

public UserDetailsService userDetailsService() {

var userDetailsService = new InMemoryUserDetailsManager();

var user = User.withUsername("john")

.password("12345")

.authorities("read")

.build();

userDetailsService.createUser(user); return userDetailsService;

}

@Bean

public PasswordEncoder passwordEncoder() { return NoOpPasswordEncoder.getInstance();

}

}

In this case, the UserManagementConfig class only contains the two beans that are responsible for user management: UserDetailsService and PasswordEncoder. We’ll configure the two objects as beans because this class can’t extend Web- SecurityConfigurerAdapter. The next listing shows this definition.

Listing 2.18 Defining the configuration class for authorization management

@Configuration

public class WebAuthorizationConfig extends WebSecurityConfigurerAdapter {

@Override

protected void configure(HttpSecurity http) throws Exception { http.httpBasic(); http.authorizeRequests().anyRequest().authenticated();

}

}

58	CHAPTER 2 Hello Spring Security
Here	the WebAuthorizationConfig class needs to extend WebSecurity-

ConfigurerAdapter and override the configure(HttpSecurity http) method.

NOTE You can’t have both classes extending WebSecurityConfigurer- Adapter in this case. If you do so, the dependency injection fails. You might solve the dependency injection by setting the priority for injection using the @Order annotation. But, functionally, this won’t work, as the configurations exclude each other instead of merging.

Summary

Spring Boot provides some default configurations when you add Spring Secu- rity to the dependencies of the application.

You implement the basic components for authentication and authorization:

UserDetailsService, PasswordEncoder, and AuthenticationProvider.

You can define users with the User class. A user should at least have a user- name, a password, and an authority. Authorities are actions that you allow a user to do in the context of the application.

A simple implementation of a UserDetailsService that Spring Security pro- vides is InMemoryUserDetailsManager. You can add users to such an instance of UserDetailsService to manage the user in the application’s memory.

The NoOpPasswordEncoder is an implementation of the PasswordEncoder contract that uses passwords in cleartext. This implementation is good for learning examples and (maybe) proof of concepts, but not for production- ready applications.

You can use the AuthenticationProvider contract to implement custom authentication logic in the application.

There are multiple ways to write configurations, but in a single application, you should choose and stick to one approach. This helps to make your code cleaner and easier to understand.

Part 2

Implementation

In part 1, we discussed the importance of security and how to create the Spring Boot project using Spring Security as a dependency. We also explored the essential components for authentication. Now we have a starting point.

Part 2 makes up the bulk of this book. In this part, we’ll dive into using Spring Security in application development. We’ll detail each of the Spring Security components and discuss different approaches you need to know when developing any real-world app. In part 2, you’ll find everything you need to learn about developing security features in apps with Spring Security, with plenty of example projects and two hands-on exercises. I’ll drive you through a path of knowledge with multiple subjects, from the basics to using OAuth 2, and from securing apps using imperative programming to applying security in reactive applications. And I’ll make sure what we discuss is well spiced with lessons I’ve learned in my experience with using Spring Security.

In chapters 3 and 4, you’ll learn to customize user management and how to deal with passwords. In many cases, applications rely on credentials to authenti- cate users. For this reason, discussing the management of user credentials opens the gate to further discussing authentication and authorization. We’ll continue with customizing the authentication logic in chapter 5. In chapters 6 through 11, we’ll discuss the components related to authorization. Throughout all these chapters, you’ll learn how to deal with basic elements like user details managers, password encoders, authentication providers, and filters. Knowing how to apply these components and properly understanding them enables you to solve the security requirements you’ll face in real-world scenarios.

Nowadays, many apps, and especially systems deployed in the cloud, imple- ment authentication and authorization over the OAuth 2 specification. In chap-

60	PART 2 Implementation

ters 12 through 15, you’ll learn how to implement authentication and authorization in your OAuth 2 apps, using Spring Security. In chapters 16 and 17, we’ll discuss applying authorization rules at the method level. This approach enables you to use what you learn about Spring Security in non-web apps. It also gives you more flexibility when applying restrictions in web apps. In chapter 19, you’ll learn to apply Spring Security to reactive apps. And, because there’s no development process without testing, in chapter 20, you’ll learn how to write integrations tests for your security implementations.

Throughout part 2, you’ll find chapters where we’ll use a different way to address the topic at hand. In each of these chapters, we’ll work on a requirement that helps to refresh what you’ve learned, understand how more of the subjects we discussed fit together, and also learn applications for new things. I call these the “Hands-On” chapters.

62	CHAPTER 3 Managing users

This analogy is similar to the way architectures work. With any robust framework, we use contracts to decouple the implementations of the framework from the applica- tion built upon it. With Java, we use interfaces to define the contracts. A programmer is similar to a chef, knowing how the ingredients “work” together to choose just the right “implementation.” The programmer knows the framework’s abstractions and uses those to integrate with it.

This chapter is about understanding in detail one of the fundamental roles you encountered in the first example we worked on in chapter 2—the UserDetails- Service. Along with the UserDetailsService, we’ll discuss

UserDetails, which describes the user for Spring Security.

GrantedAuthority, which allows us to define actions that the user can execute.

UserDetailsManager, which extends the UserDetailsService contract. Beyond the inherited behavior, it also describes actions like creating a user and modifying or deleting a user’s password.

From chapter 2, you already have an idea of the roles of the UserDetailsService and the PasswordEncoder in the authentication process. But we only discussed how to plug in an instance defined by you instead of using the default one configured by Spring Boot. We have more details to discuss:

What implementations are provided by Spring Security and how to use them

How to define a custom implementation for contracts and when to do so

Ways to implement interfaces that you find in real-world applications

Best practices for using these interfaces

The plan is to start with how Spring Security understands the user definition. For this, we’ll discuss the UserDetails and GrantedAuthority contracts. Then we’ll detail the UserDetailsService and how UserDetailsManager extends this contract. You’ll apply implementations for these interfaces (like the InMemoryUserDetails- Manager, the JdbcUserDetailsManager, and the LdapUserDetailsManager). When these implementations aren’t a good fit for your system, you’ll write a custom implementation.

3.1Implementing authentication in Spring Security

In the previous chapter, we got started with Spring Security. In the first example, we discussed how Spring Boot defines some defaults that define how a new application initially works. You have also learned how to override these defaults using various alternatives that we often find in apps. But we only considered the surface of these so that you have an idea of what we’ll be doing. In this chapter, and chapters 4 and 5, we’ll discuss these interfaces in more detail, together with different implementations and where you might find them in real-world applications.

Describing the user

65

app that you are working on, and you need to make your choice wisely. But to be able to choose, you first need to know what you can choose from.

3.2Describing the user

In this section, you’ll learn how to describe the users of your application such that Spring Security understands them. Learning how to represent users and make the framework aware of them is an essential step in building an authentication flow. Based on the user, the application makes a decision—a call to a certain functionality is or isn’t allowed. To work with users, you first need to understand how to define the pro- totype of the user in your application. In this section, I describe by example how to establish a blueprint for your users in a Spring Security application.

For Spring Security, a user definition should respect the UserDetails contract. The UserDetails contract represents the user as understood by Spring Security. The class of your application that describes the user has to implement this interface, and in this way, the framework understands it.

3.2.1Demystifying the definition of the UserDetails contract

In this section, you’ll learn how to implement the UserDetails interface to describe the users in your application. We’ll discuss the methods declared by the User- Details contract to understand how and why we implement each of them. Let’s start first by looking at the interface as presented in the following listing.

Listing 3.1 The UserDetails interface

public interface UserDetails extends Serializable { String getUsername(); String getPassword();

Collection<? extends GrantedAuthority>

➥getAuthorities(); boolean isAccountNonExpired(); boolean isAccountNonLocked();

boolean isCredentialsNonExpired(); boolean isEnabled();

}

The getUsername() and getPassword() methods return, as you’d expect, the username and the password. The app uses these values in the process of authentica- tion, and these are the only details related to authentication from this contract. The other five methods all relate to authorizing the user for accessing the application’s resources.

Generally, the app should allow a user to do some actions that are meaningful in the application’s context. For example, the user should be able to read data, write data, or delete data. We say a user has or hasn’t the privilege to perform an action, and an authority represents the privilege a user has. We implement the getAuthorities() method to return the group of authorities granted for a user.

66	CHAPTER 3 Managing users

NOTE As you’ll learn in chapter 7, Spring Security uses authorities to refer either to fine-grained privileges or to roles, which are groups of privileges. To make your reading more effortless, in this book, I refer to the fine-grained privileges as authorities.

Furthermore, as seen in the UserDetails contract, a user can

Let the account expire

Lock the account

Let the credentials expire

Disable the account

If you choose to implement these user restrictions in your application’s logic, you need to override the following methods: isAccountNonExpired(), isAccount- NonLocked(), isCredentialsNonExpired(), isEnabled(), such that those needing to be enabled return true. Not all applications have accounts that expire or get locked with certain conditions. If you do not need to implement these functional- ities in your application, you can simply make these four methods return true.

NOTE The names of the last four methods in the UserDetails interface may sound strange. One could argue that these are not wisely chosen in terms of clean coding and maintainability. For example, the name isAccountNon- Expired() looks like a double negation, and at first sight, might create con- fusion. But analyze all four method names with attention. These are named such that they all return false for the case in which the authorization should fail and true otherwise. This is the right approach because the human mind tends to associate the word “false” with negativity and the word “true” with positive scenarios.

3.2.2Detailing on the GrantedAuthority contract

As you observed in the definition of the UserDetails interface in section 3.2.1, the actions granted for a user are called authorities. In chapters 7 and 8, we’ll write autho- rization configurations based on these user authorities. So it’s essential to know how to define them.

The authorities represent what the user can do in your application. Without authorities, all users would be equal. While there are simple applications in which the users are equal, in most practical scenarios, an application defines multiple kinds of users. An application might have users that can only read specific information, while others also can modify the data. And you need to make your application differentiate between them, depending on the functional requirements of the application, which are the authorities a user needs. To describe the authorities in Spring Security, you use the GrantedAuthority interface.

Before we discuss implementing UserDetails, let’s understand the Granted- Authority interface. We use this interface in the definition of the user details. It rep- resents a privilege granted to the user. A user can have none to any number of

Describing the user

67

authorities, and usually, they have at least one. Here’s the implementation of the GrantedAuthority definition:

public interface GrantedAuthority extends Serializable { String getAuthority();

}

To create an authority, you only need to find a name for that privilege so you can refer to it later when writing the authorization rules. For example, a user can read the records managed by the application or delete them. You write the authorization rules based on the names you give to these actions. In chapters 7 and 8, you’ll learn about writing authorization rules based on a user’s authorities.

In this chapter, we’ll implement the getAuthority() method to return the authority’s name as a String. The GrantedAuthority interface has only one abstract method, and in this book, you often find examples in which we use a lambda expression for its implementation. Another possibility is to use the SimpleGranted- Authority class to create authority instances.

The SimpleGrantedAuthority class offers a way to create immutable instances of the type GrantedAuthority. You provide the authority name when building the instance. In the next code snippet, you’ll find two examples of implementing a GrantedAuthority. Here we make use of a lambda expression and then use the SimpleGrantedAuthority class:

GrantedAuthority g1 = () -> "READ";

GrantedAuthority g2 = new SimpleGrantedAuthority("READ");

NOTE It is good practice to verify that the interface is marked as functional with the @FunctionalInterface annotation before implementing it with lambda expressions. The reason for this practice is that if the interface is not marked as functional, it can mean that its developers reserve the right to add more abstract methods to it in future versions. In Spring Security, the GrantedAuthority interface is not marked as functional. However, we’ll use lambda expressions in this book to implement that interface to make the code shorter and easier to read, even it it’s not something I recommend you do in a real-world project.

3.2.3Writing a minimal implementation of UserDetails

In this section, you’ll write your first implementation of the UserDetails contract. We start with a basic implementation in which each method returns a static value. Then we change it to a version that you’ll more likely find in a practical scenario, and one that allows you to have multiple and different instances of users. Now that you know how to implement the UserDetails and GrantedAuthority interfaces, we can write the simplest definition of a user for an application.

With a class named DummyUser, let’s implement a minimal description of a user as in listing 3.2. I use this class mainly to demonstrate implementing the methods for the

68	CHAPTER 3 Managing users

UserDetails contract. Instances of this class always refer to only one user, "bill", who has the password "12345" and an authority named "READ".

Listing 3.2 The DummyUser class

public class DummyUser implements UserDetails {

@Override

public String getUsername() { return "bill";

}

@Override

public String getPassword() { return "12345";

}

// Omitted code

}

The class in the listing 3.2 implements the UserDetails interface and needs to implement all its methods. You find here the implementation of getUsername() and getPassword(). In this example, these methods only return a fixed value for each of the properties.

Next, we add a definition for the list of authorities. Listing 3.3 shows the imple- mentation of the getAuthorities() method. This method returns a collection with only one implementation of the GrantedAuthority interface.

Listing 3.3 Implementation of the getAuthorities() method

public class DummyUser implements UserDetails {

// Omitted code

@Override

public Collection<? extends GrantedAuthority> getAuthorities() { return List.of(() -> "READ");

}

// Omitted code

}

Finally, you have to add an implementation for the last four methods of the UserDetails interface. For the DummyUser class, these always return true, which means that the user is forever active and usable. You find the examples in the follow- ing listing.

Describing the user

69

Listing 3.4 Implementation of the last four UserDetails interface methods

public class DummyUser implements UserDetails {

// Omitted code

@Override

public boolean isAccountNonExpired() { return true;

}

@Override

public boolean isAccountNonLocked() { return true;

}

@Override

public boolean isCredentialsNonExpired() { return true;

}

@Override

public boolean isEnabled() { return true;

}

// Omitted code

}

Of course, this minimal implementation means that all instances of the class represent the same user. It’s a good start to understanding the contract, but not something you would do in a real application. For a real application, you should create a class that you can use to generate instances that can represent different users. In this case, your definition would at least have the username and the password as attributes in the class, as shown in the next listing.

Listing 3.5 A more practical implementation of the UserDetails interface

public class SimpleUser implements UserDetails {

private final String username; private final String password;

public SimpleUser(String username, String password) { this.username = username;

this.password = password;

}

@Override

public String getUsername() { return this.username;

}

72	CHAPTER 3 Managing users

Listing 3.9 The User class has two responsibilities

@Entity

public class User implements UserDetails {

@Id

private int id;

private String username; private String password; private String authority;

@Override

public String getUsername() { return this.username;

}

@Override

public String getPassword() { return this.password;

}

public String getAuthority() { return this.authority;

}

@Override

public Collection<? extends GrantedAuthority> getAuthorities() { return List.of(() -> this.authority);

}

// Omitted code

}

The class contains JPA annotations, getters, and setters, of which both getUsername() and getPassword()override the methods in the UserDetails contract. It has a get- Authority() method that returns a String, as well as a getAuthorities() method that returns a Collection. The getAuthority() method is just a getter in the class, while getAuthorities() implements the method in the UserDetails interface. And things get even more complicated when adding relationships to other entities. Again, this code isn’t friendly at all!

How can we write this code to be cleaner? The root of the muddy aspect of the pre- vious code example is a mix of two responsibilities. While it’s true that you need both in the application, in this case, nobody says that you have to put these into the same class. Let’s try to separate those by defining a separate class called SecurityUser, which decorates the User class. As listing 3.10 shows, the SecurityUser class imple- ments the UserDetails contract and uses that to plug our user into the Spring Secu- rity architecture. The User class has only its JPA entity responsibility remaining.

74	CHAPTER 3 Managing users

that the SecurityUser makes no sense without a User entity, we make the field final. You have to provide the user through the constructor. The SecurityUser class deco- rates the User entity class and adds the needed code related to the Spring Security con- tract without mixing the code into a JPA entity, thereby implementing multiple different tasks.

NOTE You can find different approaches to separate the two responsibilities. I don’t want to say that the approach I present in this section is the best or the only one. Usually, the way you choose to implement the class design varies a lot from one case to another. But the main idea is the same: avoid mixing responsibilities and try to write your code as decoupled as possible to increase the maintainability of your app.

3.3Instructing Spring Security on how to manage users

In the previous section, you implemented the UserDetails contract to describe users such that Spring Security understands them. But how does Spring Security man- age users? Where are they taken from when comparing credentials, and how do you add new users or change existing ones? In chapter 2, you learned that the framework defines a specific component to which the authentication process delegates user man- agement: the UserDetailsService instance. We even defined a UserDetails- Service to override the default implementation provided by Spring Boot.

In this section, we experiment with various ways of implementing the User- DetailsService class. You’ll understand how user management works by imple- menting the responsibility described by the UserDetailsService contract in our example. After that, you’ll find out how the UserDetailsManager interface adds more behavior to the contract defined by the UserDetailsService. At the end of this section, we’ll use the provided implementations of the UserDetailsManager interface offered by Spring Security. We’ll write an example project where we’ll use one of the best known implementations provided by Spring Security, the JdbcUser- DetailsManager. Learning this, you’ll know how to tell Spring Security where to find users, which is essential in the authentication flow.

3.3.1Understanding the UserDetailsService contract

In this section, you’ll learn about the UserDetailsService interface definition. Before understanding how and why to implement it, you must first understand the contract. It is time to detail more on the UserDetailsService and how to work with implementations of this component. The UserDetailsService interface contains only one method, as follows:

public interface UserDetailsService {

UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;

}

78	CHAPTER 3 Managing users

Finally, we create a simple endpoint and test the implementation. The following list- ing defines the endpoint.

Listing 3.15 The definition of the endpoint used for testing the implementation

@RestController

public class HelloController {

@GetMapping("/hello") public String hello() {

return "Hello!";

}

}

When calling the endpoint using cURL, we observe that for user John with password 12345, we get back an HTTP 200 OK. If we use something else, the application returns 401 Unauthorized.

curl -u john:12345 http://localhost:8080/hello

The response body is

Hello!

3.3.3Implementing the UserDetailsManager contract

In this section, we discuss using and implementing the UserDetailsManager inter- face. This interface extends and adds more methods to the UserDetailsService contract. Spring Security needs the UserDetailsService contract to do the authen- tication. But generally, in applications, there is also a need for managing users. Most of the time, an app should be able to add new users or delete existing ones. In this case, we implement a more particular interface defined by Spring Security, the User- DetailsManager. It extends UserDetailsService and adds more operations that we need to implement.

public interface UserDetailsManager extends UserDetailsService { void createUser(UserDetails user);

void updateUser(UserDetails user); void deleteUser(String username);

void changePassword(String oldPassword, String newPassword); boolean userExists(String username);

}

The InMemoryUserDetailsManager object that we used in chapter 2 is actually a UserDetailsManager. At that time, we only considered its UserDetailsService characteristics, but now you understand better why we were able to call a create- User() method on the instance.

USING A JDBCUSERDETAILSMANAGER FOR USER MANAGEMENT

Beside the InMemoryUserDetailsManager, we often use another UserDetail- Manager, the JdbcUserDetailsManager. The JdbcUserDetailsManager

Instructing Spring Security on how to manage users

81

Listing 3.18 Dependencies needed to develop the example project

<dependency>

<groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId>

</dependency>

<dependency>

<groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId>

</dependency>

<dependency>

<groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-jdbc</artifactId>

</dependency>

<dependency>

<groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope>

</dependency>

NOTE In your examples, you can use any SQL database technology as long as you add the correct JDBC driver to the dependencies.

You can configure a data source in the application.properties file of the project or as a separate bean. If you choose to use the application.properties file, you need to add the following lines to that file:

spring.datasource.url=jdbc:mysql://localhost/spring spring.datasource.username=<your user> spring.datasource.password=<your password> spring.datasource.initialization-mode=always

In the configuration class of the project, you define the UserDetailsService and the PasswordEncoder. The JdbcUserDetailsManager needs the DataSource to connect to the database. The data source can be autowired through a parameter of the method (as presented in the next listing) or through an attribute of the class.

Listing 3.19 Registering the JdbcUserDetailsManager in the configuration class

@Configuration

public class ProjectConfig {

@Bean

public UserDetailsService userDetailsService(DataSource dataSource) { return new JdbcUserDetailsManager(dataSource);

}

@Bean

public PasswordEncoder passwordEncoder() { return NoOpPasswordEncoder.getInstance();

}

}

82	CHAPTER 3 Managing users

To access any endpoint of the application, you now need to use HTTP Basic authenti- cation with one of the users stored in the database. To prove this, we create a new end- point as shown in the following listing and then call it with cURL.

Listing 3.20 The test endpoint to check the implementation

@RestController

public class HelloController {

@GetMapping("/hello") public String hello() {

return "Hello!";

}

}

In the next code snippet, you find the result when calling the endpoint with the cor- rect username and password:

curl -u john:12345 http://localhost:8080/hello

The response to the call is

Hello!

The JdbcUserDetailsManager also allows you to configure the queries used. In the previous example, we made sure we used the exact names for the tables and columns, as the JdbcUserDetailsManager implementation expects those. But it could be that for your application, these names are not the best choice. The next listing shows how to override the queries for the JdbcUserDetailsManager.

Listing 3.21 Changing JdbcUserDetailsManager’s queries to find the user

@Bean

public UserDetailsService userDetailsService(DataSource dataSource) { String usersByUsernameQuery =

"select username, password, enabled ➥from users where username = ?";

String authsByUserQuery = "select username, authority

➥from spring.authorities where username = ?";

var userDetailsManager = new JdbcUserDetailsManager(dataSource); userDetailsManager.setUsersByUsernameQuery(usersByUsernameQuery); userDetailsManager.setAuthoritiesByUsernameQuery(authsByUserQuery); return userDetailsManager;

}

In the same way, we can change all the queries used by the JdbcUserDetails- Manager implementation.

Instructing Spring Security on how to manage users

83

Exercise: Write a similar application for which you name the tables and the col- umns differently in the database. Override the queries for the JdbcUserDetails- Manager implementation (for example, the authentication works with a new table structure). The project ssia-ch3-ex2 features a possible solution.

USING AN LDAPUSERDETAILSMANAGER FOR USER MANAGEMENT

Spring Security also offers an implementation of UserDetailsManager for LDAP. Even if it is less popular than the JdbcUserDetailsManager, you can count on it if you need to integrate with an LDAP system for user management. In the project ssia- ch3-ex3, you can find a simple demonstration of using the LdapUserDetails- Manager. Because I can’t use a real LDAP server for this demonstration, I have set up an embedded one in my Spring Boot application. To set up the embedded LDAP server, I defined a simple LDAP Data Interchange Format (LDIF) file. The following listing shows the content of my LDIF file.

Listing 3.22 The definition of the LDIF file

dn: dc=springframework,dc=org	Defines the
objectclass: top
	base entity
objectclass: domain
objectclass: extensibleObject
dc: springframework
dn: ou=groups,dc=springframework,dc=org		Defines a
objectclass: top
		group entity
objectclass: organizationalUnit
ou: groups
dn: uid=john,ou=groups,dc=springframework,dc=org		Defines
objectclass: top
		a user
objectclass: person

objectclass: organizationalPerson

objectclass: inetOrgPerson

cn: John

sn: John

uid: john

userPassword: 12345

In the LDIF file, I add only one user for which we need to test the app’s behavior at the end of this example. We can add the LDIF file directly to the resources folder. This way, it’s automatically in the classpath, so we can easily refer to it later. I named the LDIF file server.ldif. To work with LDAP and to allow Spring Boot to start an embedded LDAP server, you need to add pom.xml to the dependencies as in the fol- lowing code snippet:

<dependency>

<groupId>org.springframework.security</groupId> <artifactId>spring-security-ldap</artifactId>

</dependency>

84	CHAPTER 3 Managing users

<dependency>

<groupId>com.unboundid</groupId> <artifactId>unboundid-ldapsdk</artifactId>

</dependency>

In the application.properties file, you also need to add the configurations for the embedded LDAP server as presented in the following code snippet. The values the app needs to boot the embedded LDAP server include the location of the LDIF file, a port for the LDAP server, and the base domain component (DN) label values:

spring.ldap.embedded.ldif=classpath:server.ldif spring.ldap.embedded.base-dn=dc=springframework,dc=org spring.ldap.embedded.port=33389

Once you have an LDAP server for authentication, you can configure your application to use it. The next listing shows you how to configure the LdapUserDetails- Manager to enable your app to authenticate users through the LDAP server.

Listing 3.23 The definition of the LdapUserDetailsManager in the configuration file

Adds a UserDetailsService

implementation to the Spring context

@Configuration

public class ProjectConfig extends WebSecurityConfigurerAdapter {

@Bean			Creates a context source
public UserDetailsService userDetailsService() {			to specify the address of
	var cs = new DefaultSpringSecurityContextSource(		the LDAP server
	"ldap://127.0.0.1:33389/dc=springframework,dc=org");
	cs.afterPropertiesSet();		Creates the
	var manager = new LdapUserDetailsManager(cs);		LdapUserDetailsManager instance
	manager.setUsernameMapper(
	new DefaultLdapUsernameToDnMapper("ou=groups", "uid"));
	manager.setGroupSearchBase("ou=groups");		Sets a username mapper
			to instruct the
	return manager;	Sets the group search	LdapUserDetailsManager
}			on how to search for users
		base that the app needs

to search for users

@Bean

public PasswordEncoder passwordEncoder() { return NoOpPasswordEncoder.getInstance();

}

}

Let’s also create a simple endpoint to test the security configuration. I added a con- troller class as presented in the next code snippet:

@RestController

public class HelloController {

Summary

85

@GetMapping("/hello") public String hello() {

return "Hello!";

}

}

Now start the app and call the /hello endpoint. You need to authenticate with user John if you want the app to allow you to call the endpoint. The next code snippet shows you the result of calling the endpoint with cURL:

curl -u john:12345 http://localhost:8080/hello

The response to the call is

Hello!

Summary

The UserDetails interface is the contract you use to describe a user in Spring Security.

The UserDetailsService interface is the contract that Spring Security expects you to implement in the authentication architecture to describe the way the application obtains user details.

The UserDetailsManager interface extends the UserDetailsService and adds the behavior related to creating, changing, or deleting a user.

Spring Security provides a few implementations of the UserDetailsManager contract. Among these are InMemoryUserDetailsManager, JdbcUser- DetailsManager, and LdapUserDetailsManager.

The JdbcUserDetailsManager has the advantage of directly using JDBC and does not lock the application in to other frameworks.

88	CHAPTER 4 Dealing with passwords

not. Every system stores passwords encoded in some way. You preferably store them hashed so that there’s no chance someone can read the passwords. The Password- Encoder can also encode passwords. The methods encode() and matches(), which the contract declares, are actually the definition of its responsibility. Both of these are parts of the same contract because these are strongly linked, one to the other. The way the application encodes a password is related to the way the password is validated. Let’s first review the content of the PasswordEncoder interface:

public interface PasswordEncoder {

String encode(CharSequence rawPassword);

boolean matches(CharSequence rawPassword, String encodedPassword);

default boolean upgradeEncoding(String encodedPassword) { return false;

}

}

The interface defines two abstract methods and one with a default implementation. The abstract encode() and matches() methods are also the ones that you most often hear about when dealing with a PasswordEncoder implementation.

The purpose of the encode(CharSequence rawPassword) method is to return a transformation of a provided string. In terms of Spring Security functionality, it’s used to provide encryption or a hash for a given password. You can use the matches(CharSequence rawPassword, String encodedPassword) method afterward to check if an encoded string matches a raw password. You use the matches() method in the authentication process to test a provided password against a set of known credentials. The third method, called upgradeEncoding(Char- Sequence encodedPassword), defaults to false in the contract. If you override it to return true, then the encoded password is encoded again for better security.

In some cases, encoding the encoded password can make it more challenging to obtain the cleartext password from the result. In general, this is some kind of obscu- rity that I, personally, don’t like. But the framework offers you this possibility if you think it applies to your case.

4.1.2Implementing the PasswordEncoder contract

As you observed, the two methods matches() and encode() have a strong relation- ship. If you override them, they should always correspond in terms of functionality: a string returned by the encode() method should always be verifiable with the matches() method of the same PasswordEncoder. In this section, you’ll implement the PasswordEncoder contract and define the two abstract methods declared by the interface. Knowing how to implement the PasswordEncoder, you can choose how the application manages passwords for the authentication process. The most straight- forward implementation is a password encoder that considers passwords in plain text: that is, it doesn’t do any encoding on the password.

90	CHAPTER 4 Dealing with passwords

input. To validate a hash against an input, the matches() method hashes the raw password in its input and compares it for equality with the hash against which it does the validation.

Listing 4.3 The implementation of the method to hash the input with SHA-512

private String hashWithSHA512(String input) { StringBuilder result = new StringBuilder(); try {

MessageDigest md = MessageDigest.getInstance("SHA-512"); byte [] digested = md.digest(input.getBytes());

for (int i = 0; i < digested.length; i++) { result.append(Integer.toHexString(0xFF & digested[i]));

}

}catch (NoSuchAlgorithmException e) {

throw new RuntimeException("Bad algorithm");

}

return result.toString();

}

You’ll learn better options to do this in the next section, so don’t bother too much with this code for now.

4.1.3Choosing from the provided implementations of PasswordEncoder

While knowing how to implement your PasswordEncoder is powerful, you also have to be aware that Spring Security already provides you with some advantageous imple- mentations. If one of these matches your application, you don’t need to rewrite it. In this section, we discuss the PasswordEncoder implementation options that Spring Security provides. These are

NoOpPasswordEncoder—Doesn’t encode the password but keeps it in clear- text. We use this implementation only for examples. Because it doesn’t hash the password, you should never use it in a real-world scenario.

StandardPasswordEncoder—Uses SHA-256 to hash the password. This implementation is now deprecated, and you shouldn’t use it for your new implemen- tations. The reason why it’s deprecated is that it uses a hashing algorithm that we don’t consider strong enough anymore, but you might still find this imple- mentation used in existing applications.

Pbkdf2PasswordEncoder—Uses the password-based key derivation function 2 (PBKDF2).

BCryptPasswordEncoder—Uses a bcrypt strong hashing function to encode the password.

SCryptPasswordEncoder—Uses an scrypt hashing function to encode the password.

Understanding the PasswordEncoder contract

91

For more about hashing and these algorithms, you can find a good discussion in chap- ter 2 of Real-World Cryptography by David Wong (Manning, 2020). Here’s the link:

https://livebook.manning.com/book/real-world-cryptography/chapter-2/

Let’s take a look at some examples of how to create instances of these types of PasswordEncoder implementations. The NoOpPasswordEncoder doesn’t encode the password. It has an implementation similar to the PlainTextPasswordEncoder from our example in listing 4.1. For this reason, we only use this password encoder with theoretical examples. Also, the NoOpPasswordEncoder class is designed as a sin- gleton. You can’t call its constructor directly from outside the class, but you can use the NoOpPasswordEncoder.getInstance() method to obtain the instance of the class like this:

PasswordEncoder p = NoOpPasswordEncoder.getInstance();

The StandardPasswordEncoder implementation provided by Spring Security uses SHA-256 to hash the password. For the StandardPasswordEncoder, you can pro- vide a secret used in the hashing process. You set the value of this secret by the con- structor’s parameter. If you choose to call the no-arguments constructor, the implementation uses the empty string as a value for the key. However, the Standard- PasswordEncoder is deprecated now, and I don’t recommend that you use it with your new implementations. You could find older applications or legacy code that still uses it, so this is why you should be aware of it. The next code snippet shows you how to create instances of this password encoder:

PasswordEncoder p = new StandardPasswordEncoder();

PasswordEncoder p = new StandardPasswordEncoder("secret");

Another option offered by Spring Security is the Pbkdf2PasswordEncoder imple- mentation that uses the PBKDF2 for password encoding. To create instances of the Pbkdf2PasswordEncoder, you have the following options:

PasswordEncoder p = new Pbkdf2PasswordEncoder(); PasswordEncoder p = new Pbkdf2PasswordEncoder("secret"); PasswordEncoder p = new Pbkdf2PasswordEncoder("secret", 185000, 256);

The PBKDF2 is a pretty easy, slow-hashing function that performs an HMAC as many times as specified by an iterations argument. The three parameters received by the last call are the value of a key used for the encoding process, the number of iterations used to encode the password, and the size of the hash. The second and third parame- ters can influence the strength of the result. You can choose more or fewer iterations, as well as the length of the result. The longer the hash, the more powerful the pass- word. However, be aware that performance is affected by these values: the more iterations, the more resources your application consumes. You should make a wise

92	CHAPTER 4 Dealing with passwords

compromise between the resources consumed for generating the hash and the needed strength of the encoding.

NOTE In this book, I refer to several cryptography concepts that you might like to know more about. For relevant information on HMACs and other cryptography details, I recommend Real-World Cryptography by David Wong (Manning, 2020). Chapter 3 of that book provides detailed information about HMAC. You can find the book at https://livebook.manning.com/ book/real-world-cryptography/chapter-3/.

If you do not specify one of the second or third values for the Pbkdf2Password- Encoder implementation, the defaults are 185000 for the number of iterations and 256 for the length of the result. You can specify custom values for the number of iterations and the length of the result by choosing one of the other two overloaded constructors: the one without parameters, Pbkdf2PasswordEncoder(), or the one that receives only the secret value as a parameter, Pbkdf2PasswordEncoder ("secret").

Another excellent option offered by Spring Security is the BCryptPassword- Encoder, which uses a bcrypt strong hashing function to encode the password. You can instantiate the BCryptPasswordEncoder by calling the no-arguments construc- tor. But you also have the option to specify a strength coefficient representing the log rounds (logarithmic rounds) used in the encoding process. Moreover, you can also alter the SecureRandom instance used for encoding:

PasswordEncoder p = new BCryptPasswordEncoder();

PasswordEncoder p = new BCryptPasswordEncoder(4);

SecureRandom s = SecureRandom.getInstanceStrong();

PasswordEncoder p = new BCryptPasswordEncoder(4, s);

The log rounds value that you provide affects the number of iterations the hashing operation uses. The number of iterations used is 2log rounds. For the iteration number

computation, the value for the log rounds can only be between 4 and 31. You can specify this by calling one of the second or third overloaded constructors, as shown in the previous code snippet.

The last option I present to you is SCryptPasswordEncoder (figure 4.2). This password encoder uses an scrypt hashing function. For the ScryptPassword- Encoder, you have two options to create its instances:

PasswordEncoder p = new SCryptPasswordEncoder();

PasswordEncoder p = new SCryptPasswordEncoder(16384, 8, 1, 32, 64);

The values in the previous examples are the ones used if you create the instance by calling the no-arguments constructor.

Understanding the PasswordEncoder contract	93
Memory cost	Key length

PasswordEncoder p = new SCryptPasswordEncoder(16384, 8, 1, 32, 64);

CPU cost	Salt length
	Parallelization coefficient

Figure 4.2 The SCryptPasswordEncoder constructor takes five parameters and allows you to configure CPU cost, memory cost, key length, and salt length.

4.1.4Multiple encoding strategies with DelegatingPasswordEncoder

In this section, we discuss the cases in which an authentication flow must apply various implementations for matching the passwords. You’ll also learn how to apply a useful tool that acts as a PasswordEncoder in your application. Instead of having its own implementation, this tool delegates to other objects that implement the Password- Encoder interface.

In some applications, you might find it useful to have various password encoders and choose from these depending on some specific configuration. A common sce- nario in which I find the DelegatingPasswordEncoder in production applications is when the encoding algorithm is changed, starting with a particular version of the application. Imagine somebody finds a vulnerability in the currently used algorithm, and you want to change it for newly registered users, but you do not want to change it for existing credentials. So you end up having multiple kinds of hashes. How do you manage this case? While it isn’t the only approach for this scenario, a good choice is to use a DelegatingPasswordEncoder object.

The DelegatingPasswordEncoder is an implementation of the Password- Encoder interface that, instead of implementing its encoding algorithm, delegates to another instance of an implementation of the same contract. The hash starts with a prefix naming the algorithm used to define that hash. The DelegatingPassword- Encoder delegates to the correct implementation of the PasswordEncoder based on the prefix of the password.

It sounds complicated, but with an example, you can observe that it is pretty easy. Figure 4.3 presents the relationship among the PasswordEncoder instances. The

DelegatingPasswordEncoder has a list of PasswordEncoder implementations to which it delegates. The DelegatingPasswordEncoder stores each of the instances in a map. The NoOpPasswordEncoder is assigned to the key noop, while the BCryptPasswordEncoder implementation is assigned the key bcrypt. When the password has the prefix {noop}, the DelegatingPasswordEncoder delegates the

96	CHAPTER 4 Dealing with passwords

For convenience, Spring Security offers a way to create a DelegatingPassword- Encoder that has a map to all the standard provided implementations of Password- Encoder. The PasswordEncoderFactories class provides a createDelegating- PasswordEncoder() static method that returns the implementation of the DelegatingPasswordEncoder with bcrypt as a default encoder:

PasswordEncoder passwordEncoder = PasswordEncoderFactories.createDelegatingPasswordEncoder();

Encoding vs. encrypting vs. hashing

In the previous sections, I often used the terms encoding, encrypting, and hashing. I want to briefly clarify these terms and the way we use them throughout the book.

Encoding refers to any transformation of a given input. For example, if we have a func- tion x that reverses a string, function x -> y applied to ABCD produces DCBA.

Encryption is a particular type of encoding where, to obtain the output, you provide both the input value and a key. The key makes it possible for choosing afterward who should be able to reverse the function (obtain the input from the output). The sim- plest form of representing encryption as a function looks like this:

(x, k) -> y

where x is the input, k is the key, and y is the result of the encryption. This way, an individual knows the key can use a known function to obtain the input from the output (y, k) -> x. We call this reverse function decryption. If the key used for encryption is the same as the one used for decryption, we usually call it a symmetric key.

If we have two different keys for encryption ((x, k1) -> y) and decryption ((y, k2) -> x), then we say that the encryption is done with asymmetric keys. Then (k1,

k2) is called a key pair. The key used for encryption, k1, is also referred to as the public key, while k2 is known as the private one. This way, only the owner of the pri- vate key can decrypt the data.

Hashing is a particular type of encoding, except the function is only one way. That is, from an output y of the hashing function, you cannot get back the input x. However, there should always be a way to check if an output y corresponds to an input x, so we can understand the hashing as a pair of functions for encoding and matching. If hashing is x -> y, then we should also have a matching function (x,y) -> boolean.

Sometimes the hashing function could also use a random value added to the input: (x, k) -> y. We refer to this value as the salt. The salt makes the function stron- ger, enforcing the difficulty of applying a reverse function to obtain the input from the result.

More about the Spring Security Crypto module

97

To summarize the contracts we have discussed and applied up to now in this book, table 4.1 briefly describes each of the components.

Table 4.1 The interfaces that represent the main contracts for authentication flow in Spring Security

Contract	Description
UserDetails	Represents the user as seen by Spring Security.
GrantedAuthority	Defines an action within the purpose of the application that is allowable to
	the user (for example, read, write, delete, etc.).
UserDetailsService	Represents the object used to retrieve user details by username.
UserDetailsManager	A more particular contract for UserDetailsService. Besides retrieving
	the user by username, it can also be used to mutate a collection of users
	or a specific user.
PasswordEncoder	Specifies how the password is encrypted or hashed and how to check if a
	given encoded string matches a plaintext password.

4.2More about the Spring Security Crypto module

In this section, we discuss the Spring Security Crypto module (SSCM), which is the part of Spring Security that deals with cryptography. Using encryption and decryption functions and generating keys isn’t offered out of the box with the Java language. And this constrains developers when adding dependencies that provide a more accessible approach to these features.

To make our lives easier, Spring Security also provides its own solution, which enables you to reduce the dependencies of your projects by eliminating the need to use a separate library. The password encoders are also part of the SSCM, even if we have treated them separately in previous sections. In this section, we discuss what other options the SSCM offers that are related to cryptography. You’ll see examples of how to use two essential features from the SSCM:

Key generators—Objects used to generate keys for hashing and encryption algo- rithms

Encryptors—Objects used to encrypt and decrypt data

4.2.1Using key generators

In this section, we discuss key generators. A key generator is an object used to generate a specific kind of key, generally needed for an encryption or hashing algorithm. The implementations of key generators that Spring Security offers are great utility tools. You’ll prefer to use these implementations rather than adding another dependency for your application, and this is why I recommend that you become aware of them. Let’s see some code examples of how to create and apply the key generators.

98CHAPTER 4 Dealing with passwords

Two interfaces represent the two main types of key generators: BytesKey- Generator and StringKeyGenerator. We can build them directly by making use of the factory class KeyGenerators. You can use a string key generator, represented by the StringKeyGenerator contract, to obtain a key as a string. Usually, we use this key as a salt value for a hashing or encryption algorithm. You can find the definition of the StringKeyGenerator contract in this code snippet:

public interface StringKeyGenerator {

String generateKey();

}

The generator has only a generateKey() method that returns a string representing the key value. The next code snippet presents an example of how to obtain a String- KeyGenerator instance and how to use it to get a salt value:

StringKeyGenerator keyGenerator = KeyGenerators.string();

String salt = keyGenerator.generateKey();

The generator creates an 8-byte key, and it encodes that as a hexadecimal string. The method returns the result of these operations as a string. The second interface describing a key generator is the BytesKeyGenerator, which is defined as follows:

public interface BytesKeyGenerator {

int getKeyLength(); byte[] generateKey();

}

In addition to the generateKey() method that returns the key as a byte[], the interface defines another method that returns the key length in number of bytes. A default ByteKeyGenerator generates keys of 8-byte length:

BytesKeyGenerator keyGenerator = KeyGenerators.secureRandom(); byte [] key = keyGenerator.generateKey();

int keyLength = keyGenerator.getKeyLength();

In the previous code snippet, the key generator generates keys of 8-byte length. If you want to specify a different key length, you can do this when obtaining the key genera- tor instance by providing the desired value to the KeyGenerators.secure- Random() method:

BytesKeyGenerator keyGenerator = KeyGenerators.secureRandom(16);

The keys generated by the BytesKeyGenerator created with the KeyGenerators-

.secureRandom() method are unique for each call of the generateKey() method.

More about the Spring Security Crypto module

99

In some cases, we prefer an implementation that returns the same key value for each call of the same key generator. In this case, we can create a BytesKeyGenerator with the KeyGenerators.shared(int length) method. In this code snippet, key1 and key2 have the same value:

BytesKeyGenerator keyGenerator = KeyGenerators.shared(16); byte [] key1 = keyGenerator.generateKey();

byte [] key2 = keyGenerator.generateKey();

4.2.2Using encryptors for encryption and decryption operations

In this section, we apply the implementations of encryptors that Spring Security offers with code examples. An encryptor is an object that implements an encryption algo- rithm. When talking about security, encryption and decryption are common opera- tions, so expect to need these within your application.

We often need to encrypt data either when sending it between components of the system or when persisting it. The operations provided by an encryptor are encryption and decryption. There are two types of encryptors defined by the SSCM: Bytes- Encryptor and TextEncryptor. While they have similar responsibilities, they treat different data types. TextEncryptor manages data as a string. Its methods receive strings as inputs and return strings as outputs, as you can see from the definition of its interface:

public interface TextEncryptor {

String encrypt(String text);

String decrypt(String encryptedText);

}

The BytesEncryptor is more generic. You provide its input data as a byte array:

public interface BytesEncryptor {

byte[] encrypt(byte[] byteArray);

byte[] decrypt(byte[] encryptedByteArray);

}

Let’s find out what options we have to build and use an encryptor. The factory class Encryptors offers us multiple possibilities. For BytesEncryptor, we could use the Encryptors.standard() or the Encryptors.stronger() methods like this:

String salt = KeyGenerators.string().generateKey();

String password = "secret";

String valueToEncrypt = "HELLO";

BytesEncryptor e = Encryptors.standard(password, salt); byte [] encrypted = e.encrypt(valueToEncrypt.getBytes()); byte [] decrypted = e.decrypt(encrypted);